├── .gitignore ├── Makefile ├── README.md ├── make.bat └── source ├── _templates └── indexcontent.html ├── community.rst ├── community ├── code_of_conduct.rst ├── contributing.rst ├── issue_tracking.rst └── join_the_discussion.rst ├── conf.py ├── contents.rst ├── faq.rst ├── images ├── add_remove.png ├── arch_overview_communication.png ├── arch_overview_journal.png ├── arch_overview_layers.png ├── arch_overview_ledger.png ├── control_panel.png ├── logfile.png ├── net_framework.png ├── new_platform_solution.png ├── python_all_users.png ├── python_complete.png ├── python_customize.png ├── python_default_path.png ├── python_progress_bar.png ├── services_console.png ├── validator_download_folder.png ├── validator_files.png ├── validator_progress_bar.png ├── validator_uninstall_progress_bar.png ├── visual_studio_custom.png └── visual_studio_x64_compiler.png ├── introduction.rst ├── mktplace_developers_guide.rst ├── mktplace_developers_guide ├── mktclient.rst ├── mktplace_data_model.rst ├── mktplace_initial_state.rst ├── mktplace_messages.rst └── mktplace_transactions.rst ├── sawtooth_developers_guide.rst ├── sawtooth_developers_guide ├── architecture_overview.rst ├── sawtooth_vagrant.rst ├── signing_transactions.rst ├── validator_network_launcher.rst ├── web_api │ ├── block.rst │ ├── echo.rst │ ├── forward.rst │ ├── index.rst │ ├── initiate.rst │ ├── store.rst │ └── transaction.rst └── workload_simulator.rst ├── sysadmin_guide.rst ├── sysadmin_guide ├── installation_sles.rst ├── installation_ubuntu.rst ├── installation_windows.rst ├── network_configuration.rst ├── packaging_sles.rst ├── packaging_ubuntu.rst └── packaging_windows.rst ├── tutorial.rst ├── tutorial └── txnvalidator.js └── txn_family_tutorial.rst /.gitignore: -------------------------------------------------------------------------------- 1 | /build/ 2 | /source/sawtooth_api/ 3 | /source/mktplace_api/ 4 | .DS_Store 5 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXAPIDOC = sphinx-apidoc 8 | PAPER = 9 | BUILDDIR = build 10 | SAWTOOTH_REPO = ../sawtooth-core 11 | MKTPLACE_REPO = ../sawtooth-mktplace 12 | 13 | # User-friendly check for sphinx-build 14 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 15 | $(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/) 16 | endif 17 | 18 | # Internal variables. 19 | PAPEROPT_a4 = -D latex_paper_size=a4 20 | PAPEROPT_letter = -D latex_paper_size=letter 21 | ALLSPHINXOPTS = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 22 | # the i18n builder cannot share the environment and doctrees with the others 23 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 24 | 25 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext sawtooth_apidoc mktplace_apidoc 26 | 27 | help: 28 | @echo "Please use \`make ' where is one of" 29 | @echo " html to make standalone HTML files" 30 | @echo " dirhtml to make HTML files named index.html in directories" 31 | @echo " singlehtml to make a single large HTML file" 32 | @echo " pickle to make pickle files" 33 | @echo " json to make JSON files" 34 | @echo " htmlhelp to make HTML files and a HTML help project" 35 | @echo " qthelp to make HTML files and a qthelp project" 36 | @echo " applehelp to make an Apple Help Book" 37 | @echo " devhelp to make HTML files and a Devhelp project" 38 | @echo " epub to make an epub" 39 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 40 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 41 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 42 | @echo " text to make text files" 43 | @echo " man to make manual pages" 44 | @echo " texinfo to make Texinfo files" 45 | @echo " info to make Texinfo files and run them through makeinfo" 46 | @echo " gettext to make PO message catalogs" 47 | @echo " changes to make an overview of all changed/added/deprecated items" 48 | @echo " xml to make Docutils-native XML files" 49 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 50 | @echo " linkcheck to check all external links for integrity" 51 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 52 | @echo " coverage to run coverage check of the documentation (if enabled)" 53 | 54 | clean: 55 | rm -rf $(BUILDDIR)/* source/sawtooth_api source/mktplace_api 56 | 57 | sawtooth_apidoc: 58 | $(SPHINXAPIDOC) -o source/sawtooth_api -M -f -e -H "Distributed Ledger Python API" $(SAWTOOTH_REPO) $(SAWTOOTH_REPO)/setup.py 59 | 60 | mktplace_apidoc: 61 | $(SPHINXAPIDOC) -o source/mktplace_api -M -f -e -H "MarketPlace Python API" $(MKTPLACE_REPO) $(MKTPLACE_REPO)/setup.py 62 | 63 | html: sawtooth_apidoc mktplace_apidoc 64 | @mkdir -p source/_static 65 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 66 | @echo 67 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 68 | 69 | dirhtml: 70 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 71 | @echo 72 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 73 | 74 | singlehtml: 75 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 76 | @echo 77 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 78 | 79 | pickle: 80 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 81 | @echo 82 | @echo "Build finished; now you can process the pickle files." 83 | 84 | json: 85 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 86 | @echo 87 | @echo "Build finished; now you can process the JSON files." 88 | 89 | htmlhelp: 90 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 91 | @echo 92 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 93 | ".hhp project file in $(BUILDDIR)/htmlhelp." 94 | 95 | qthelp: 96 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 97 | @echo 98 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 99 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 100 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IntelMaidenLane.qhcp" 101 | @echo "To view the help file:" 102 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IntelMaidenLane.qhc" 103 | 104 | applehelp: 105 | $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp 106 | @echo 107 | @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." 108 | @echo "N.B. You won't be able to view it unless you put it in" \ 109 | "~/Library/Documentation/Help or install it in your application" \ 110 | "bundle." 111 | 112 | devhelp: 113 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 114 | @echo 115 | @echo "Build finished." 116 | @echo "To view the help file:" 117 | @echo "# mkdir -p $$HOME/.local/share/devhelp/IntelMaidenLane" 118 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/IntelMaidenLane" 119 | @echo "# devhelp" 120 | 121 | epub: 122 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 123 | @echo 124 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 125 | 126 | latex: 127 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 128 | @echo 129 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 130 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 131 | "(use \`make latexpdf' here to do that automatically)." 132 | 133 | latexpdf: sawtooth_apidoc mktplace_apidoc 134 | @mkdir -p source/_static 135 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 136 | @echo "Running LaTeX files through pdflatex..." 137 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 138 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 139 | 140 | latexpdfja: 141 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 142 | @echo "Running LaTeX files through platex and dvipdfmx..." 143 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 144 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 145 | 146 | text: 147 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 148 | @echo 149 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 150 | 151 | man: 152 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 153 | @echo 154 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 155 | 156 | texinfo: 157 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 158 | @echo 159 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 160 | @echo "Run \`make' in that directory to run these through makeinfo" \ 161 | "(use \`make info' here to do that automatically)." 162 | 163 | info: 164 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 165 | @echo "Running Texinfo files through makeinfo..." 166 | make -C $(BUILDDIR)/texinfo info 167 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 168 | 169 | gettext: 170 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 171 | @echo 172 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 173 | 174 | changes: 175 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 176 | @echo 177 | @echo "The overview file is in $(BUILDDIR)/changes." 178 | 179 | linkcheck: 180 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 181 | @echo 182 | @echo "Link check complete; look for any errors in the above output " \ 183 | "or in $(BUILDDIR)/linkcheck/output.txt." 184 | 185 | doctest: 186 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 187 | @echo "Testing of doctests in the sources finished, look at the " \ 188 | "results in $(BUILDDIR)/doctest/output.txt." 189 | 190 | coverage: 191 | $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage 192 | @echo "Testing of coverage in the sources finished, look at the " \ 193 | "results in $(BUILDDIR)/coverage/python.txt." 194 | 195 | xml: 196 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 197 | @echo 198 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 199 | 200 | pseudoxml: 201 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 202 | @echo 203 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 204 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Incubation Notice 2 | ================= 3 | 4 | This project is a Hyperledger project in _Incubation_. It was proposed to the 5 | community and documented [here](http://bit.ly/1T6eVBH). Information on what 6 | _Incubation_ entails can be found in the [Hyperledger Project Lifecycle document](https://goo.gl/4edNRc). 7 | 8 | Distributed Ledger 9 | ================== 10 | 11 | Distributed Ledger is a highly modular platform for building, deploying and 12 | running distributed ledgers. 13 | 14 | Security Notice 15 | =============== 16 | This project is intended for experimental usage and is not secure. 17 | Do not use this project for security sensitive applications. 18 | Please see the 19 | [Introduction](http://intelledger.github.io/introduction.html) 20 | for more details. 21 | 22 | Documentation 23 | ============= 24 | 25 | Documentation is available at: http://intelledger.github.io/. 26 | 27 | Content 28 | ======= 29 | 30 | This repository contains the documentation source files. The documentation 31 | generated from these source files can be found at 32 | [Distributed Ledger Documentation](http://intelledger.github.io/index.html). 33 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source 10 | set I18NSPHINXOPTS=%SPHINXOPTS% source 11 | if NOT "%PAPER%" == "" ( 12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% 14 | ) 15 | 16 | if "%1" == "" goto help 17 | 18 | if "%1" == "help" ( 19 | :help 20 | echo.Please use `make ^` where ^ is one of 21 | echo. html to make standalone HTML files 22 | echo. dirhtml to make HTML files named index.html in directories 23 | echo. singlehtml to make a single large HTML file 24 | echo. pickle to make pickle files 25 | echo. json to make JSON files 26 | echo. htmlhelp to make HTML files and a HTML help project 27 | echo. qthelp to make HTML files and a qthelp project 28 | echo. devhelp to make HTML files and a Devhelp project 29 | echo. epub to make an epub 30 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 31 | echo. text to make text files 32 | echo. man to make manual pages 33 | echo. texinfo to make Texinfo files 34 | echo. gettext to make PO message catalogs 35 | echo. changes to make an overview over all changed/added/deprecated items 36 | echo. xml to make Docutils-native XML files 37 | echo. pseudoxml to make pseudoxml-XML files for display purposes 38 | echo. linkcheck to check all external links for integrity 39 | echo. doctest to run all doctests embedded in the documentation if enabled 40 | echo. coverage to run coverage check of the documentation if enabled 41 | goto end 42 | ) 43 | 44 | if "%1" == "clean" ( 45 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 46 | del /q /s %BUILDDIR%\* 47 | goto end 48 | ) 49 | 50 | 51 | REM Check if sphinx-build is available and fallback to Python version if any 52 | %SPHINXBUILD% 2> nul 53 | if errorlevel 9009 goto sphinx_python 54 | goto sphinx_ok 55 | 56 | :sphinx_python 57 | 58 | set SPHINXBUILD=python -m sphinx.__init__ 59 | %SPHINXBUILD% 2> nul 60 | if errorlevel 9009 ( 61 | echo. 62 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 63 | echo.installed, then set the SPHINXBUILD environment variable to point 64 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 65 | echo.may add the Sphinx directory to PATH. 66 | echo. 67 | echo.If you don't have Sphinx installed, grab it from 68 | echo.http://sphinx-doc.org/ 69 | exit /b 1 70 | ) 71 | 72 | :sphinx_ok 73 | 74 | 75 | if "%1" == "html" ( 76 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html 77 | if errorlevel 1 exit /b 1 78 | echo. 79 | echo.Build finished. The HTML pages are in %BUILDDIR%/html. 80 | goto end 81 | ) 82 | 83 | if "%1" == "dirhtml" ( 84 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml 85 | if errorlevel 1 exit /b 1 86 | echo. 87 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. 88 | goto end 89 | ) 90 | 91 | if "%1" == "singlehtml" ( 92 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml 93 | if errorlevel 1 exit /b 1 94 | echo. 95 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. 96 | goto end 97 | ) 98 | 99 | if "%1" == "pickle" ( 100 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle 101 | if errorlevel 1 exit /b 1 102 | echo. 103 | echo.Build finished; now you can process the pickle files. 104 | goto end 105 | ) 106 | 107 | if "%1" == "json" ( 108 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json 109 | if errorlevel 1 exit /b 1 110 | echo. 111 | echo.Build finished; now you can process the JSON files. 112 | goto end 113 | ) 114 | 115 | if "%1" == "htmlhelp" ( 116 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp 117 | if errorlevel 1 exit /b 1 118 | echo. 119 | echo.Build finished; now you can run HTML Help Workshop with the ^ 120 | .hhp project file in %BUILDDIR%/htmlhelp. 121 | goto end 122 | ) 123 | 124 | if "%1" == "qthelp" ( 125 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp 126 | if errorlevel 1 exit /b 1 127 | echo. 128 | echo.Build finished; now you can run "qcollectiongenerator" with the ^ 129 | .qhcp project file in %BUILDDIR%/qthelp, like this: 130 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\IntelMaidenLane.qhcp 131 | echo.To view the help file: 132 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\IntelMaidenLane.ghc 133 | goto end 134 | ) 135 | 136 | if "%1" == "devhelp" ( 137 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp 138 | if errorlevel 1 exit /b 1 139 | echo. 140 | echo.Build finished. 141 | goto end 142 | ) 143 | 144 | if "%1" == "epub" ( 145 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub 146 | if errorlevel 1 exit /b 1 147 | echo. 148 | echo.Build finished. The epub file is in %BUILDDIR%/epub. 149 | goto end 150 | ) 151 | 152 | if "%1" == "latex" ( 153 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 154 | if errorlevel 1 exit /b 1 155 | echo. 156 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. 157 | goto end 158 | ) 159 | 160 | if "%1" == "latexpdf" ( 161 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 162 | cd %BUILDDIR%/latex 163 | make all-pdf 164 | cd %~dp0 165 | echo. 166 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 167 | goto end 168 | ) 169 | 170 | if "%1" == "latexpdfja" ( 171 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 172 | cd %BUILDDIR%/latex 173 | make all-pdf-ja 174 | cd %~dp0 175 | echo. 176 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 177 | goto end 178 | ) 179 | 180 | if "%1" == "text" ( 181 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text 182 | if errorlevel 1 exit /b 1 183 | echo. 184 | echo.Build finished. The text files are in %BUILDDIR%/text. 185 | goto end 186 | ) 187 | 188 | if "%1" == "man" ( 189 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man 190 | if errorlevel 1 exit /b 1 191 | echo. 192 | echo.Build finished. The manual pages are in %BUILDDIR%/man. 193 | goto end 194 | ) 195 | 196 | if "%1" == "texinfo" ( 197 | %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo 198 | if errorlevel 1 exit /b 1 199 | echo. 200 | echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. 201 | goto end 202 | ) 203 | 204 | if "%1" == "gettext" ( 205 | %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale 206 | if errorlevel 1 exit /b 1 207 | echo. 208 | echo.Build finished. The message catalogs are in %BUILDDIR%/locale. 209 | goto end 210 | ) 211 | 212 | if "%1" == "changes" ( 213 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes 214 | if errorlevel 1 exit /b 1 215 | echo. 216 | echo.The overview file is in %BUILDDIR%/changes. 217 | goto end 218 | ) 219 | 220 | if "%1" == "linkcheck" ( 221 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck 222 | if errorlevel 1 exit /b 1 223 | echo. 224 | echo.Link check complete; look for any errors in the above output ^ 225 | or in %BUILDDIR%/linkcheck/output.txt. 226 | goto end 227 | ) 228 | 229 | if "%1" == "doctest" ( 230 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest 231 | if errorlevel 1 exit /b 1 232 | echo. 233 | echo.Testing of doctests in the sources finished, look at the ^ 234 | results in %BUILDDIR%/doctest/output.txt. 235 | goto end 236 | ) 237 | 238 | if "%1" == "coverage" ( 239 | %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage 240 | if errorlevel 1 exit /b 1 241 | echo. 242 | echo.Testing of coverage in the sources finished, look at the ^ 243 | results in %BUILDDIR%/coverage/python.txt. 244 | goto end 245 | ) 246 | 247 | if "%1" == "xml" ( 248 | %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml 249 | if errorlevel 1 exit /b 1 250 | echo. 251 | echo.Build finished. The XML files are in %BUILDDIR%/xml. 252 | goto end 253 | ) 254 | 255 | if "%1" == "pseudoxml" ( 256 | %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml 257 | if errorlevel 1 exit /b 1 258 | echo. 259 | echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. 260 | goto end 261 | ) 262 | 263 | :end 264 | -------------------------------------------------------------------------------- /source/_templates/indexcontent.html: -------------------------------------------------------------------------------- 1 | {%- extends "layout.html" %} 2 | {% set title = 'Overview' %} 3 | {% block body %} 4 | 5 |

Sawtooth Lake documentation

6 | 7 |

{% trans %}Introduction{% endtrans %}
8 | {% trans %}learn about Sawtooth Lake{% endtrans %}

9 | 10 |

{% trans %}Tutorial{% endtrans %}
11 | {% trans %}get the Sawtooth Lake up and running{% endtrans %}

12 | 13 |

{% trans %}Transaction Family Tutorial{% endtrans %}
14 | {% trans %}create a new Sawtooth Lake transaction family{% endtrans %}

15 | 16 |

{% trans %}Distributed Ledger Developer's Guide{% endtrans %}
17 | {% trans %}extend or contribute code and documentation{% endtrans %}

18 | 19 |

{% trans %}MarketPlace Developer's Guide{% endtrans %}
20 | {% trans %}understanding the MarketPlace transaction family{% endtrans %}

21 | 22 |

{% trans %}System Administrator's Guide{% endtrans %}
23 | {% trans %}installation, configuration, and maintenance{% endtrans %}

24 | 25 |

{% trans %}Community{% endtrans %}
26 | {% trans %}join the conversation{% endtrans %}

27 | 28 |

{% trans %}FAQ{% endtrans %}
29 | {% trans %}frequently asked questions{% endtrans %}

30 | 31 |

{% trans %}Table of Contents{% endtrans %}
32 | {% trans %}detailed list of documentation sections{% endtrans %}

33 | 34 | 35 | {% endblock %} 36 | -------------------------------------------------------------------------------- /source/community.rst: -------------------------------------------------------------------------------- 1 | ********* 2 | Community 3 | ********* 4 | 5 | Welcome to the Sawtooth Lake community! 6 | 7 | For help topics, we recommend joining us on Slack (link below). 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | 12 | community/join_the_discussion 13 | community/issue_tracking 14 | community/contributing 15 | community/code_of_conduct 16 | 17 | -------------------------------------------------------------------------------- /source/community/code_of_conduct.rst: -------------------------------------------------------------------------------- 1 | 2 | Code of Conduct 3 | =============== 4 | 5 | When participating, please be respectful and courteous. 6 | 7 | Sawtooth Lake uses the `Hyperledger Project Code of Conduct 8 | `_. 9 | 10 | -------------------------------------------------------------------------------- /source/community/contributing.rst: -------------------------------------------------------------------------------- 1 | ------------ 2 | Contributing 3 | ------------ 4 | 5 | ================== 6 | Ways to Contribute 7 | ================== 8 | 9 | Contributions by the community help grow and optimize the capabilities of 10 | Sawtooth Lake, and are the most effective method of having a positive impact on 11 | the project. 12 | 13 | **Different ways you can contribute** 14 | 15 | * Bugs or Issues (issues or defects found when working with Sawtooth Lake) 16 | * Core Features & Enhancements (expanded capabilities or optimization) 17 | * Arcade Features (games that demonstrate Sawtooth Lake such as Go and Checkers) 18 | * New or Enhanced Documentation (improve existing documentation or create new) 19 | * Testing Events and Results (functional, performance or scalability) 20 | 21 | **Unassigned JIRA Issues** 22 | 23 | More specific items can be found in :ref:`jira`. Any JIRA items which are 24 | unassigned are probably still open. If in doubt, ask on :ref:`slack` about 25 | the particular JIRA issue. 26 | 27 | ============== 28 | Commit Process 29 | ============== 30 | 31 | Distributed Ledger is Apache 2.0 licensed and accepts contributions via GitHub 32 | pull requests. When contributing code please do the following: 33 | 34 | * Fork the repository and make your changes in a feature branch. 35 | * Please include unit and integration test changes. 36 | * Please ensure the unit and integration tests run successfully. Both are run 37 | with `nose2`, but integration tests are only run if the environment variable 38 | ENABLE_INTEGRATION_TESTS is set. 39 | * Please ensure that lint passes by running './bin/run_lint'. The command 40 | should produce no output if there are no lint errors. 41 | 42 | **Pull Request Guidelines** 43 | 44 | Pull requests can contain a single commit or multiple commits. The most 45 | important part is that a single commit maps to a single fix or enhancement. 46 | 47 | Here are a few scenarios: 48 | 49 | * If a pull request adds a feature but also fixes two bugs, then the pull 50 | request should have three commits, one commit each for the feature and two 51 | bug fixes 52 | * If a PR is opened with 5 commits that was work involved to fix a single issue, 53 | it should be rebased to a single commit 54 | * If a PR is opened with 5 commits, with the first three to fix one issue and 55 | the second two to fix a separate issue, then it should be rebased to two 56 | commits, one for each issue 57 | 58 | Your pull request should be rebased against the current master branch. Please do 59 | not merge the current master branch in with your topic branch, nor use the 60 | Update Branch button provided by GitHub on the pull request page. 61 | 62 | **Signed-off-by** 63 | 64 | Commits must include Signed-off-by in the commit message (git commit -s). 65 | This indicates that you agree the commit satisifies the DCO: 66 | http://developercertificate.org/. 67 | -------------------------------------------------------------------------------- /source/community/issue_tracking.rst: -------------------------------------------------------------------------------- 1 | ************** 2 | Issue Tracking 3 | ************** 4 | 5 | .. _jira: 6 | 7 | JIRA 8 | ==== 9 | 10 | We use JIRA as our issue tracking system. The JIRA instance is hosted by 11 | the Hyperledger Project, and Sawtooth Lake uses the key *STL*: 12 | 13 | https://jira.hyperledger.org/projects/STL/issues/ 14 | 15 | To report issues, you will need to login to JIRA, which requires a 16 | Linux Foundation account. To setup a Linux Foundation account, go to: 17 | 18 | https://identity.linuxfoundation.org/ 19 | 20 | How to Report an Issue 21 | ====================== 22 | 23 | Issues should be created in JIRA under the Sawtooth Lake project (which 24 | uses the *STL* JIRA key). 25 | 26 | Before reporting an issue, please review current open issues to see if there 27 | are any matches. If there is a match, comment with a +1, or "Also seeing this 28 | issue". If any environment details differ, please add those with your comment 29 | to the matching issue. 30 | 31 | If you would like, you could also bring up the issue on :ref:`slack` 32 | for initial feedback before submitting the issue in JIRA. 33 | 34 | When reporting an issue, please provide as much detail as possible about how 35 | to reproduce it. If possible, provide instructions for how to reproduce the 36 | issue within the vagrant development environment. 37 | 38 | -------------------------------------------------------------------------------- /source/community/join_the_discussion.rst: -------------------------------------------------------------------------------- 1 | ******************* 2 | Join the Discussion 3 | ******************* 4 | 5 | .. _slack: 6 | 7 | Slack 8 | ===== 9 | 10 | Slack is the place to go for real-time chat about everything from quick help to 11 | involved discussion. 12 | 13 | You can find us on the Hyperledger Project's Slack instance, in the #sawtooth 14 | channel. 15 | 16 | If you need an invite, go to the `Hyperledger Project Slack Invitition 17 | Request Page `_. 18 | 19 | The slack instance is at: 20 | 21 | `Hyperledger Project Slack `_ 22 | *#sawtooth* 23 | 24 | Mailing Lists 25 | ============= 26 | 27 | The Sawtooth Lake mailing list is hosted by the Hyperledger Project: 28 | 29 | `hyperledger-stl Mailing List `_ 30 | 31 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Sawtooth Lake documentation build configuration file, created by 4 | # sphinx-quickstart on Wed Dec 2 11:03:19 2015. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | import shlex 18 | 19 | # If extensions (or modules to document with autodoc) are in another directory, 20 | # add these directories to sys.path here. If the directory is relative to the 21 | # documentation root, use os.path.abspath to make it absolute, like shown here. 22 | #sys.path.insert(0, os.path.abspath('.')) 23 | 24 | # -- General configuration ------------------------------------------------ 25 | 26 | # If your documentation needs a minimal Sphinx version, state it here. 27 | #needs_sphinx = '1.0' 28 | 29 | # Add any Sphinx extension module names here, as strings. They can be 30 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 31 | # ones. 32 | extensions = [ 33 | 'sphinx.ext.todo', 34 | 'sphinx.ext.ifconfig', 35 | 'sphinx.ext.autodoc', 36 | 'sphinx.ext.viewcode', 37 | 'sphinx.ext.napoleon', 38 | 'sphinxcontrib.httpdomain', 39 | ] 40 | 41 | # Autodoc settings 42 | autodoc_member_order = 'bysource' 43 | autoclass_content = 'both' 44 | 45 | # Napoleon settings 46 | napoleon_use_ivar = True 47 | napoleon_include_special_with_doc = True 48 | 49 | # Add any paths that contain templates here, relative to this directory. 50 | templates_path = ['_templates'] 51 | 52 | # The suffix(es) of source filenames. 53 | # You can specify multiple suffix as a list of string: 54 | # source_suffix = ['.rst', '.md'] 55 | source_suffix = '.rst' 56 | 57 | # The encoding of source files. 58 | #source_encoding = 'utf-8-sig' 59 | 60 | # The master toctree document. 61 | master_doc = 'contents' 62 | 63 | # General information about the project. 64 | project = u'Sawtooth Lake' 65 | copyright = u'2015-2016, Intel Corporation' 66 | author = u'Intel Corporation' 67 | 68 | # The version info for the project you're documenting, acts as replacement for 69 | # |version| and |release|, also used in various other places throughout the 70 | # built documents. 71 | # 72 | # The short X.Y version. 73 | version = 'latest' 74 | # The full version, including alpha/beta/rc tags. 75 | release = 'latest' 76 | 77 | # The language for content autogenerated by Sphinx. Refer to documentation 78 | # for a list of supported languages. 79 | # 80 | # This is also used if you do content translation via gettext catalogs. 81 | # Usually you set "language" from the command line for these cases. 82 | language = None 83 | 84 | # There are two options for replacing |today|: either, you set today to some 85 | # non-false value, then it is used: 86 | #today = '' 87 | # Else, today_fmt is used as the format for a strftime call. 88 | #today_fmt = '%B %d, %Y' 89 | 90 | # List of patterns, relative to source directory, that match files and 91 | # directories to ignore when looking for source files. 92 | exclude_patterns = ['community/how_to_report_issues.rst'] 93 | 94 | # The reST default role (used for this markup: `text`) to use for all 95 | # documents. 96 | #default_role = None 97 | 98 | # If true, '()' will be appended to :func: etc. cross-reference text. 99 | #add_function_parentheses = True 100 | 101 | # If true, the current module name will be prepended to all description 102 | # unit titles (such as .. function::). 103 | #add_module_names = True 104 | 105 | # If true, sectionauthor and moduleauthor directives will be shown in the 106 | # output. They are ignored by default. 107 | #show_authors = False 108 | 109 | # The name of the Pygments (syntax highlighting) style to use. 110 | pygments_style = 'sphinx' 111 | 112 | # A list of ignored prefixes for module index sorting. 113 | #modindex_common_prefix = [] 114 | 115 | # If true, keep warnings as "system message" paragraphs in the built documents. 116 | #keep_warnings = False 117 | 118 | # If true, `todo` and `todoList` produce output, else they produce nothing. 119 | todo_include_todos = True 120 | 121 | 122 | # -- Options for HTML output ---------------------------------------------- 123 | 124 | # The theme to use for HTML and HTML Help pages. See the documentation for 125 | # a list of builtin themes. 126 | html_theme = 'sphinx_rtd_theme' 127 | 128 | # Theme options are theme-specific and customize the look and feel of a theme 129 | # further. For a list of options available for each theme, see the 130 | # documentation. 131 | #html_theme_options = {} 132 | 133 | # Add any paths that contain custom themes here, relative to this directory. 134 | #html_theme_path = [] 135 | 136 | # The name for this set of Sphinx documents. If None, it defaults to 137 | # " v documentation". 138 | #html_title = None 139 | 140 | # A shorter title for the navigation bar. Default is the same as html_title. 141 | #html_short_title = None 142 | 143 | # The name of an image file (relative to this directory) to place at the top 144 | # of the sidebar. 145 | #html_logo = None 146 | 147 | # The name of an image file (within the static path) to use as favicon of the 148 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 149 | # pixels large. 150 | #html_favicon = None 151 | 152 | # Add any paths that contain custom static files (such as style sheets) here, 153 | # relative to this directory. They are copied after the builtin static files, 154 | # so a file named "default.css" will overwrite the builtin "default.css". 155 | html_static_path = ['_static'] 156 | 157 | # Add any extra paths that contain custom files (such as robots.txt or 158 | # .htaccess) here, relative to this directory. These files are copied 159 | # directly to the root of the documentation. 160 | #html_extra_path = [] 161 | 162 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 163 | # using the given strftime format. 164 | #html_last_updated_fmt = '%b %d, %Y' 165 | 166 | # If true, SmartyPants will be used to convert quotes and dashes to 167 | # typographically correct entities. 168 | #html_use_smartypants = True 169 | 170 | # Custom sidebar templates, maps document names to template names. 171 | #html_sidebars = {} 172 | 173 | # Additional templates that should be rendered to pages, maps page names to 174 | # template names. 175 | html_additional_pages = { 176 | 'index': 'indexcontent.html' 177 | } 178 | 179 | # If false, no module index is generated. 180 | #html_domain_indices = True 181 | 182 | # If false, no index is generated. 183 | #html_use_index = True 184 | 185 | # If true, the index is split into individual pages for each letter. 186 | #html_split_index = False 187 | 188 | # If true, links to the reST sources are added to the pages. 189 | #html_show_sourcelink = True 190 | 191 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 192 | html_show_sphinx = False 193 | 194 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 195 | #html_show_copyright = True 196 | 197 | # If true, an OpenSearch description file will be output, and all pages will 198 | # contain a tag referring to it. The value of this option must be the 199 | # base URL from which the finished HTML is served. 200 | #html_use_opensearch = '' 201 | 202 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 203 | #html_file_suffix = None 204 | 205 | # Language to be used for generating the HTML full-text search index. 206 | # Sphinx supports the following languages: 207 | # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' 208 | # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' 209 | #html_search_language = 'en' 210 | 211 | # A dictionary with options for the search language support, empty by default. 212 | # Now only 'ja' uses this config value 213 | #html_search_options = {'type': 'default'} 214 | 215 | # The name of a javascript file (relative to the configuration directory) that 216 | # implements a search results scorer. If empty, the default will be used. 217 | #html_search_scorer = 'scorer.js' 218 | 219 | # Output file base name for HTML help builder. 220 | htmlhelp_basename = 'SawtoothLakeDoc' 221 | 222 | PREAMBLE = '' 223 | 224 | # -- Options for LaTeX output --------------------------------------------- 225 | 226 | latex_elements = { 227 | # The paper size ('letterpaper' or 'a4paper'). 228 | #'papersize': 'letterpaper', 229 | 230 | # The font size ('10pt', '11pt' or '12pt'). 231 | #'pointsize': '10pt', 232 | 233 | # Additional stuff for the LaTeX preamble. 234 | 'preamble': PREAMBLE, 235 | 236 | # Latex figure (float) alignment 237 | #'figure_align': 'htbp', 238 | } 239 | 240 | # Grouping the document tree into LaTeX files. List of tuples 241 | # (source start file, target name, title, 242 | # author, documentclass [howto, manual, or own class]). 243 | latex_documents = [ 244 | (master_doc, 'SawtoothLake.tex', u'Sawtooth Lake Documentation', 245 | u'Intel Corporation', 'manual'), 246 | ('tutorial', 'SawtoothLakeTutorial.tex', u'Sawtooth Lake Tutorial', 247 | u'Intel Corporation', 'howto'), 248 | ('sawtooth_developers_guide', 'SawtoothLakeDevelopersGuide.tex', u'Sawtooth Lake Developer\'s Guide', 249 | u'Intel Corporation', 'howto'), 250 | ('mktplace_developers_guide', 'MarketPlaceDevelopersGuide.tex', u'MarketPlace Developer\'s Guide', 251 | u'Intel Corporation', 'howto'), 252 | ('sysadmin_guide', 'SawtoothLakeSysadminGuide.tex', u'Sawtooth Lake Systems Administrator\'s Guide', 253 | u'Intel Corporation', 'howto') 254 | ] 255 | 256 | # The name of an image file (relative to this directory) to place at the top of 257 | # the title page. 258 | #latex_logo = None 259 | 260 | # For "manual" documents, if this is true, then toplevel headings are parts, 261 | # not chapters. 262 | #latex_use_parts = False 263 | 264 | # If true, show page references after internal links. 265 | #latex_show_pagerefs = False 266 | 267 | # If true, show URL addresses after external links. 268 | #latex_show_urls = False 269 | 270 | # Documents to append as an appendix to all manuals. 271 | #latex_appendices = [] 272 | 273 | # If false, no module index is generated. 274 | #latex_domain_indices = True 275 | 276 | 277 | # -- Options for manual page output --------------------------------------- 278 | 279 | # One entry per manual page. List of tuples 280 | # (source start file, name, description, authors, manual section). 281 | man_pages = [ 282 | (master_doc, 'intelmaidenlane', u'Sawtooth Lake Documentation', 283 | [author], 1) 284 | ] 285 | 286 | # If true, show URL addresses after external links. 287 | #man_show_urls = False 288 | 289 | 290 | # -- Options for Texinfo output ------------------------------------------- 291 | 292 | # Grouping the document tree into Texinfo files. List of tuples 293 | # (source start file, target name, title, author, 294 | # dir menu entry, description, category) 295 | texinfo_documents = [ 296 | (master_doc, 'SawtoothLake', u'Sawtooth Lake Documentation', 297 | author, 'SawtoothLake', 'One line description of project.', 298 | 'Miscellaneous'), 299 | ] 300 | 301 | # Documents to append as an appendix to all manuals. 302 | #texinfo_appendices = [] 303 | 304 | # If false, no module index is generated. 305 | #texinfo_domain_indices = True 306 | 307 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 308 | #texinfo_show_urls = 'footnote' 309 | 310 | # If true, do not generate a @detailmenu in the "Top" node's menu. 311 | #texinfo_no_detailmenu = False 312 | -------------------------------------------------------------------------------- /source/contents.rst: -------------------------------------------------------------------------------- 1 | 2 | Table of Contents 3 | ================= 4 | 5 | .. toctree:: 6 | 7 | introduction.rst 8 | tutorial.rst 9 | txn_family_tutorial.rst 10 | sawtooth_developers_guide.rst 11 | mktplace_developers_guide.rst 12 | sysadmin_guide.rst 13 | community.rst 14 | faq.rst 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /source/faq.rst: -------------------------------------------------------------------------------- 1 | *** 2 | FAQ 3 | *** 4 | 5 | Validators 6 | ========== 7 | 8 | 9 | How do I change the validator configuration? 10 | -------------------------------------------- 11 | 12 | The default configuration file is at 13 | `sawtooth-validator/etc/txnvalidator.js`. We recommend you copy that 14 | file to a new file in the same directory and make changes to the new file. 15 | When starting the txnvalidator, use the `--config` argument to reference 16 | the configuration file, In this example, we have copied the 17 | `txnvalidator.js` file to `single-node.js` and modified it: 18 | 19 | .. code-block:: console 20 | 21 | $ cd /project/sawtooth-validator 22 | $ ./bin/txnvalidator -v --config ../etc/single-node.js 23 | 24 | Multiple config files can be overlaid, and all of the settings in the 25 | config file can be overridden on the command line, but that's beyond the 26 | scope of this answer. 27 | 28 | What configuration changes should I make to run a single validator? 29 | ------------------------------------------------------------------- 30 | 31 | Copy the `sawtooth-validator/etc/txnvalidator.js` to `single-node.js` and 32 | make the following changes: 33 | 34 | 35 | `TargetWaitTime` 36 | The desired mean inter-block commit time across the network. 37 | While the default is 30 seconds, we recommend 5 seconds for 38 | development and experimenting. 39 | 40 | `InitialWaitTime` 41 | This is only important when starting the first node which 42 | will initialize the ledger (i.e. `GenesisLedger` is true). 43 | This will often be the case when testing. We recommend setting 44 | it to the same value as `TargetWaitTime`. 45 | -------------------------------------------------------------------------------- /source/images/add_remove.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/add_remove.png -------------------------------------------------------------------------------- /source/images/arch_overview_communication.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/arch_overview_communication.png -------------------------------------------------------------------------------- /source/images/arch_overview_journal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/arch_overview_journal.png -------------------------------------------------------------------------------- /source/images/arch_overview_layers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/arch_overview_layers.png -------------------------------------------------------------------------------- /source/images/arch_overview_ledger.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/arch_overview_ledger.png -------------------------------------------------------------------------------- /source/images/control_panel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/control_panel.png -------------------------------------------------------------------------------- /source/images/logfile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/logfile.png -------------------------------------------------------------------------------- /source/images/net_framework.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/net_framework.png -------------------------------------------------------------------------------- /source/images/new_platform_solution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/new_platform_solution.png -------------------------------------------------------------------------------- /source/images/python_all_users.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/python_all_users.png -------------------------------------------------------------------------------- /source/images/python_complete.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/python_complete.png -------------------------------------------------------------------------------- /source/images/python_customize.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/python_customize.png -------------------------------------------------------------------------------- /source/images/python_default_path.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/python_default_path.png -------------------------------------------------------------------------------- /source/images/python_progress_bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/python_progress_bar.png -------------------------------------------------------------------------------- /source/images/services_console.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/services_console.png -------------------------------------------------------------------------------- /source/images/validator_download_folder.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/validator_download_folder.png -------------------------------------------------------------------------------- /source/images/validator_files.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/validator_files.png -------------------------------------------------------------------------------- /source/images/validator_progress_bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/validator_progress_bar.png -------------------------------------------------------------------------------- /source/images/validator_uninstall_progress_bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/validator_uninstall_progress_bar.png -------------------------------------------------------------------------------- /source/images/visual_studio_custom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/visual_studio_custom.png -------------------------------------------------------------------------------- /source/images/visual_studio_x64_compiler.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hyperledger-archives/sawtooth-docs/74338674a16de721018d8311b35c57f443faadb7/source/images/visual_studio_x64_compiler.png -------------------------------------------------------------------------------- /source/introduction.rst: -------------------------------------------------------------------------------- 1 | ************ 2 | Introduction 3 | ************ 4 | 5 | .. caution:: 6 | 7 | This project includes a consensus algorithm, PoET (Proof of Elapsed Time), 8 | which is intended to run in a Trusted Execution Environment (TEE), such as 9 | `Intel® Software Guard Extensions (SGX) 10 | `_. 11 | This release includes software which runs outside of SGX and simulates the 12 | behavior of the PoET algorithm. It does **not** provide security in this 13 | mode. This project is intended for experimental usage and we recommend 14 | against using it for security sensitive applications. 15 | 16 | This project, called "Sawtooth Lake" is a highly modular platform for 17 | building, deploying and running distributed ledgers. Distributed ledgers 18 | provide a digital record (such as asset ownership) that is maintained 19 | without a central authority or implementation. Instead of a single, 20 | centralized database, participants in the ledger contribute resources 21 | to shared computation that ensures universal agreement on the state of 22 | the ledger. While Bitcoin is the most popular distributed ledger, the 23 | technology has been proposed for many different applications ranging 24 | from international remittance, insurance claim processing, supply chain 25 | management and the Internet of Things (IoT). 26 | 27 | Distributed ledgers generally consist of three basic components: 28 | 29 | * A data model that captures the current state of the ledger 30 | 31 | * A language of transactions that change the ledger state 32 | 33 | * A protocol used to build consensus among participants around 34 | which transactions will be accepted by the ledger. 35 | 36 | In Sawtooth Lake the data model and transaction language are implemented 37 | in a “transaction family”. While we expect users to build custom transaction 38 | families that reflect the unique requirements of their ledgers, we provide 39 | three transaction families that are sufficient for building, testing and 40 | deploying a marketplace for digital assets: 41 | 42 | * EndPointRegistry - A transaction family for registering ledger 43 | services. 44 | 45 | * IntegerKey - A transaction family used for testing deployed ledgers. 46 | 47 | * MarketPlace - A transaction family for buying, selling and trading 48 | digital assets. 49 | 50 | This set of transaction families provides an “out of the box” ledger that 51 | implements a fully functional marketplace for digital assets. 52 | 53 | 54 | Consensus 55 | ========= 56 | 57 | Consensus is the process of building agreement among a group of mutually 58 | distrusting participants. There are many different algorithms for building 59 | consensus based on requirements related to performance, scalability, 60 | consistency, threat model, and failure model. While most distributed ledgers 61 | operate with an assumption of Byzantine failures (malicious attacker), 62 | other properties are largely determined by application requirements. 63 | For example, ledgers used to record financial transactions often require 64 | high transaction rates with relatively few participants and immediate 65 | finality of commitment. Consumer markets, in contrast, require substantial 66 | aggregate throughput across a large number of participants; however, 67 | short-term finality is less important. 68 | 69 | Algorithms for achieving consensus with arbitrary faults generally require 70 | some form of voting among a known set of participants. Two general approaches 71 | have been proposed. The first, often referred to as "Nakamoto consensus", 72 | elects a leader through some form of “lottery”. The leader then proposes a 73 | block that can be added to a chain of previously committed blocks. In Bitcoin, 74 | the first participant to successfully solve a cryptographic puzzle wins 75 | the leader-election lottery. The elected leader broadcasts the new block 76 | to the rest of the participants who implicitly vote to accept the block by 77 | adding the block to a chain of accepted blocks and proposing subsequent 78 | transaction blocks that build on that chain. 79 | 80 | The second approach is based on traditional 81 | `Byzantine Fault Tolerance (BFT) 82 | `_ 83 | algorithms and uses multiple rounds of explicit votes to achieve consensus. 84 | `Ripple `_ and `Stellar `_ 85 | developed consensus protocols that extend traditional BFT for open 86 | participation. 87 | 88 | Sawtooth Lake abstracts the core concepts of consensus, isolates consensus 89 | from transaction semantics, and provides two consensus protocols with 90 | different performance trade-offs. The first, called PoET for “Proof 91 | of Elapsed Time”, is a lottery protocol that builds on trusted execution 92 | environments (TEEs) provided by Intel's SGX to address the needs of 93 | large populations of participants. The second, Quorum Voting, 94 | is an adaptation of the Ripple and Stellar consensus protocols and 95 | serves to address the needs of applications that require immediate 96 | transaction finality. 97 | 98 | 99 | Proof of Elapsed Time (PoET) 100 | ============================ 101 | 102 | For the purpose of achieving distributed consensus efficiently, 103 | a good lottery function has several characteristics: 104 | 105 | * Fairness: The function should distribute leader election 106 | across the broadest possible population of participants. 107 | 108 | * Investment: The cost of controlling the leader election 109 | process should be proportional to the value gained from it. 110 | 111 | * Verification: It should be relatively simple for all participants 112 | to verify that the leader was legitimately selected. 113 | 114 | Sawtooth Lake provides a Nakamoto consensus algorithm called PoET 115 | that uses a trusted execution environment (TEE) such as 116 | `Intel® Software Guard Extensions (SGX) 117 | `_ 118 | to ensure the safety and randomness of the leader election process 119 | without requiring the costly investment of power and specialized 120 | hardware inherent in most “proof” algorithms. Our approach 121 | is based on a guaranteed wait time provided through the TEE. 122 | 123 | Basically, every validator requests a wait time from a trusted function. 124 | The validator with the shortest wait time for a particular transaction 125 | block is elected the leader. One function, say “CreateTimer” creates 126 | a timer for a transaction block that is guaranteed to have been created 127 | by the TEE. Another function, say “CheckTimer” verifies that the timer 128 | was created by the TEE and, if it has expired, creates an attestation 129 | that can be used to verify that validator did, in fact, wait the allotted 130 | time before claiming the leadership role. 131 | 132 | The PoET leader election algorithm meets the criteria for a good lottery 133 | algorithm. It randomly distributes leadership election across the entire 134 | population of validators with distribution that is similar to what is 135 | provided by other lottery algorithms. The probability of election 136 | is proportional to the resources contributed (in this case, resources 137 | are general purpose processors with a trusted execution environment). 138 | An attestation of execution provides information for verifying that the 139 | certificate was created within the TEE (and that the validator waited 140 | the allotted time). Further, the low cost of participation increases the 141 | likelihood that the population of validators will be large, increasing 142 | the robustness of the consensus algorithm. 143 | 144 | Our “proof of processor” algorithm scales to thousands of participants 145 | and will run efficiently on any Intel processor that supports SGX. 146 | 147 | **As noted in the caution above, the current implementation simulates 148 | the behavior of the PoET algorithm running in a trusted execution environment 149 | and is not secure.** There are some benefits to using a simulator: 150 | 151 | * It does not require you to have a processor which supports SGX 152 | in order to experiment with Sawtooth Lake. 153 | 154 | * It allows running many validators (nodes) on a single system. An SGX 155 | implementation of PoET will allow only a single node per CPU socket. 156 | 157 | 158 | Getting Sawtooth Lake 159 | ===================== 160 | 161 | The Sawtooth Lake platform is distributed in source code form with 162 | an Apache license. You can get the code `here 163 | `_ and start building your own 164 | distributed ledger. 165 | 166 | Repositories 167 | ============ 168 | 169 | Here are the repositories: 170 | 171 | sawtooth-core 172 | Contains fundamental classes used throughout the Sawtooth Lake project 173 | 174 | sawtooth-validator 175 | Contains the implementation of the validator process which runs on each 176 | node 177 | 178 | sawtooth-mktplace 179 | Contains the implementation of a transaction family for buying, selling and 180 | trading digital assets, and a client program for interacting with a node 181 | to execute market transactions. 182 | 183 | sawtooth-dev-tools 184 | Contains a Vagrant environment for easily launching a network of validators 185 | 186 | sawtooth-docs 187 | Contains the source files for this documentation 188 | 189 | 190 | -------------------------------------------------------------------------------- /source/mktplace_developers_guide.rst: -------------------------------------------------------------------------------- 1 | 2 | ***************************** 3 | MarketPlace Developer's Guide 4 | ***************************** 5 | 6 | .. toctree:: 7 | :maxdepth: 2 8 | 9 | mktplace_developers_guide/mktplace_data_model.rst 10 | mktplace_developers_guide/mktplace_messages.rst 11 | mktplace_developers_guide/mktplace_transactions.rst 12 | mktplace_developers_guide/mktplace_initial_state.rst 13 | mktplace_api/modules 14 | mktplace_developers_guide/mktclient.rst 15 | 16 | -------------------------------------------------------------------------------- /source/mktplace_developers_guide/mktplace_data_model.rst: -------------------------------------------------------------------------------- 1 | .. _mktplace-data-model-label: 2 | 3 | ----------------------------------------------------------------- 4 | MarketPlace Data Model 5 | ----------------------------------------------------------------- 6 | 7 | As with other transaction families built on the Sawtooth Lake platform, 8 | the MarketPlace Transaction Family is defined by an ordered log of 9 | transactions. The implicit data model underlying the transaction family 10 | provides a means for understanding and enforcing consistency in the 11 | transaction log. This section describes the data model. 12 | 13 | Every object in the implicit data model is referenced by an identifier 14 | equivalent to the identifier of the transaction used to create the 15 | object. The transaction identifier is a SHA256 hash of the message 16 | signature. 17 | 18 | Note that the authoritative log of transactions and the cached state of 19 | objects associated with the log can be retrieved through the 20 | :ref:`web-api-index-label`. 21 | 22 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23 | Participant 24 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25 | 26 | A participant object refers to an organization or an 27 | individual. Conceptually, the participant object refers to the "owner" 28 | of an asset. Participants can create assets (and asset types), own 29 | assets, offer to exchange assets, and transfer ownership to another 30 | participant. 31 | 32 | The current model for a participant is very simple: it is a means of 33 | capturing the information necessary to authorize transactions on assets 34 | owned by the participant. 35 | 36 | .. code-block:: javascript 37 | 38 | "Participant" : 39 | { 40 | "type" : "object", 41 | "properties" : 42 | { 43 | "address" : 44 | { 45 | "type" : "string", 46 | "format" : "ADDRESS", 47 | "required" : true 48 | }, 49 | 50 | "name" : 51 | { 52 | "type" : "string", 53 | "required" : false 54 | }, 55 | 56 | "description" : 57 | { 58 | "type" : "object", 59 | "required" : false 60 | } 61 | } 62 | } 63 | 64 | The properties of a Participant include: 65 | 66 | :address: 67 | a unique derivation of the verifying key (public key) 68 | for the transaction used to register the participant; the address 69 | provides a means of verifying the identity of participants for 70 | future transaction verification and authorization 71 | 72 | :name: 73 | a unique name for the participant chosen by the person or 74 | organization creating the participant, names are constructed from 75 | printable ascii characters with the exception of '/' 76 | 77 | :description: 78 | an optional property for describing in human 79 | readable form who or what the participant represents 80 | 81 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 82 | Account 83 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 84 | 85 | An account object represents a collection of holdings and liabilities 86 | with at most one holding for each asset and at most one liability for 87 | each asset type. An account is useful primarily as a means of managing 88 | asset aggregation. 89 | 90 | .. code-block:: javascript 91 | 92 | "Account" : 93 | { 94 | "type" : "object", 95 | "properties" : 96 | { 97 | "name" : 98 | { 99 | "type" : "string", 100 | "required" : false 101 | }, 102 | 103 | "description" : 104 | { 105 | "type" : "string", 106 | "required" : false 107 | }, 108 | 109 | "creator" : 110 | { 111 | "type" : "string", 112 | "format" : "IDENTIFIER", 113 | "$ref" : "#Participant", 114 | "required" : true 115 | } 116 | } 117 | } 118 | 119 | The properties of a Account include: 120 | 121 | :name: 122 | a unique name for the object chosen by the person or 123 | organization creating the participant, names are constructed from 124 | printable ascii characters and must begin with '/' 125 | 126 | :description: 127 | an optional property for describing in human 128 | readable form who or what the object represents 129 | 130 | :creator: 131 | the identifier of the participant who registered the 132 | account object 133 | 134 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 135 | AssetType 136 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 137 | 138 | An AssetType is a descriptor for a class of Assets. The creator of an 139 | AssetType is granted the right to create Assets of the type and assign 140 | them to owners within a Holding. If the Restricted flag is True (it is 141 | True by default), then the creator of the AssetType is the only 142 | participant who can create Assets of that type. This would be 143 | appropriate, for example, for controlling creation of private stock 144 | certificates. If the Restricted flag is False, then any Participant can 145 | create Assets of that type and assign ownership to a participant within 146 | a Holding. This would be appropriate for broad asset types like "brown 147 | eggs" where many Participants are likely to create Assets of the type. 148 | 149 | .. code-block:: javascript 150 | 151 | "AssetType" : 152 | { 153 | "type" : "object", 154 | "properties" : 155 | { 156 | "name" : 157 | { 158 | "type" : "string", 159 | "required" : false 160 | }, 161 | 162 | "description" : 163 | { 164 | "type" : "string", 165 | "required" : false 166 | }, 167 | 168 | "creator" : 169 | { 170 | "type" : "string", 171 | "format" : "IDENTIFIER", 172 | "$ref" : "#Participant", 173 | "required" : true 174 | }, 175 | 176 | "restricted" : 177 | { 178 | "type" : "boolean", 179 | "default" : true, 180 | "required" : false 181 | } 182 | } 183 | } 184 | 185 | The properties of a AssetType include: 186 | 187 | :name: 188 | a unique name for the object chosen by the person or 189 | organization creating the participant, names are constructed from 190 | printable ascii characters and must begin with '/' 191 | 192 | :description: 193 | an optional property for describing in human 194 | readable form who or what the object represents 195 | 196 | :creator: 197 | the identifier of the participant who registered the 198 | account object 199 | 200 | :restricted: 201 | a flag to indicate whether the creator of the asset 202 | type (if the flag is True) or other participants (if the flag is 203 | False) can create assets of the type 204 | 205 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 206 | Asset 207 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 208 | 209 | An Asset is an instance of an Asset Type. It is intended to represent a 210 | "thing" to which value and ownership can be ascribed. Assets may be 211 | strictly intrinsic to the MarketPlace such as instances of a virtual 212 | currency or MarketPlace tokens. Alternatively, assets may provide a 213 | MarketPlace handle for digital or physical objects that exist outside of 214 | the MarketPlace. 215 | 216 | .. code-block:: javascript 217 | 218 | "Asset" : 219 | { 220 | "type" : "object", 221 | "properties" : 222 | { 223 | "name" : 224 | { 225 | "type" : "string", 226 | "required" : false 227 | }, 228 | 229 | "description" : 230 | { 231 | "type" : "string", 232 | "required" : false 233 | }, 234 | 235 | "creator" : 236 | { 237 | "format" : "IDENTIFIER", 238 | "$ref" : "#Participant", 239 | "required" : true 240 | }, 241 | 242 | "asset-type" : 243 | { 244 | "type" : "string", 245 | "format" : "IDENTIFIER", 246 | "$ref" : "#AssetType", 247 | "required" : true 248 | }, 249 | 250 | "restricted" : 251 | { 252 | "type" : "boolean", 253 | "default" : true, 254 | "required" : false 255 | }, 256 | 257 | "consumable" : 258 | { 259 | "type" : "boolean", 260 | "default" : true, 261 | "required" : false 262 | }, 263 | 264 | "divisible" : 265 | { 266 | "type" : "boolean", 267 | "default" : false, 268 | "required" : false 269 | } 270 | } 271 | } 272 | 273 | The properties of a Asset include: 274 | 275 | :name: 276 | a unique name for the object chosen by the person or 277 | organization creating the participant, names are constructed from 278 | printable ascii characters and must begin with '/' 279 | 280 | :description: 281 | an optional property for describing in human 282 | readable form who or what the object represents 283 | 284 | :creator: 285 | the identifier of the participant who registered the 286 | account object 287 | 288 | :asset-type: 289 | the identifier of the asset type from which the 290 | asset was created 291 | 292 | :restricted: 293 | a flag to indicate whether the creator of the asset 294 | (if the flag is True) or other participants (if the flag is 295 | False) can create Holdings for the asset with non-zero counts 296 | 297 | :consumable: 298 | a flag to indicate whether assets are transferred 299 | (if the flag is True) or copied (if the flag is False); Holdings 300 | with non-consumable assets always have an instance count of zero 301 | or one since a non-consumable asset can be copied infinitely 302 | 303 | :divisible: 304 | a flag to indicate whether fractional portions of 305 | assets are acceptable (if the flag is True) 306 | 307 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 308 | Holding 309 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 310 | 311 | A Holding object represents ownership of a collection of asset 312 | instances and controls the right to transfer assets to a new owner. Any 313 | participant can create an empty (i.e. the instance-count property is 0) 314 | holding for any asset. An empty Holding represents a container into 315 | which assets may be transferred. To create a holding with instance-count 316 | greater than 0, the creator of the holding must be the creator of the 317 | asset or the asset must be non-restricted. 318 | 319 | .. code-block:: javascript 320 | 321 | "Holding" : 322 | { 323 | "type" : "object", 324 | "properties" : 325 | { 326 | "name" : 327 | { 328 | "type" : "string", 329 | "required" : false 330 | }, 331 | 332 | "description" : 333 | { 334 | "type" : "string", 335 | "required" : false 336 | }, 337 | 338 | "creator" : 339 | { 340 | "type" : "string", 341 | "format" : "IDENTIFIER", 342 | "$ref" : "#Participant", 343 | "required" : true 344 | }, 345 | 346 | "account" : 347 | { 348 | "type" : "string", 349 | "format" : "IDENTIFIER", 350 | "$ref" : "#Account", 351 | "required" : true 352 | }, 353 | 354 | "asset" : 355 | { 356 | "type" : "string", 357 | "format" : "IDENTIFIER", 358 | "$ref" : "#Asset", 359 | "required" : true 360 | }, 361 | 362 | "instance-count" : 363 | { 364 | "type" : integer, 365 | "required" : true 366 | } 367 | } 368 | } 369 | 370 | The properties of a Holding include: 371 | 372 | :name: 373 | a unique name for the object chosen by the person or 374 | organization creating the participant, names are constructed from 375 | printable ascii characters and must begin with '/' 376 | 377 | :description: 378 | an optional property for describing in human 379 | readable form who or what the object represents 380 | 381 | :creator: 382 | the identifier of the participant who registered the 383 | account object 384 | 385 | :account: 386 | the identifier of the account used to scope the holding 387 | 388 | :asset: 389 | the identifier of the asset that is held 390 | 391 | :instance-count: 392 | the number of instances of the asset being held 393 | 394 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 395 | Liability 396 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 397 | 398 | Like a Holding, a Liability represents ownership though in the case of a 399 | Liability ownership is of a debt or financial obligation. Where a 400 | Holding captures ownership of specific asset instances, a Liability 401 | captures a promise or guarantee for future ownership transfer of a 402 | specific kind of asset. 403 | 404 | .. code-block:: javascript 405 | 406 | "Liability" : 407 | { 408 | "type" : "object", 409 | "properties" : 410 | { 411 | "name" : 412 | { 413 | "type" : "string", 414 | "required" : false 415 | }, 416 | 417 | "description" : 418 | { 419 | "type" : "string", 420 | "required" : false 421 | }, 422 | 423 | "creator" : 424 | { 425 | "type" : "string", 426 | "format" : "IDENTIFIER", 427 | "$ref" : "#Participant", 428 | "required" : true 429 | }, 430 | 431 | "account" : 432 | { 433 | "type" : "string", 434 | "format" : "IDENTIFIER", 435 | "$ref" : "#Account", 436 | "required" : true 437 | }, 438 | 439 | "asset-type" : 440 | { 441 | "type" : "string", 442 | "format" : "IDENTIFIER", 443 | "$ref" : "#AssetType", 444 | "required" : true 445 | }, 446 | 447 | "instance-count" : 448 | { 449 | "type" : integer, 450 | "required" : true 451 | }, 452 | 453 | "guarantor" : 454 | { 455 | "type" : "string", 456 | "format" : "IDENTIFIER", 457 | "$ref" : "#Participant", 458 | "required" : true 459 | } 460 | } 461 | } 462 | 463 | The properties of a Liability include: 464 | 465 | :name: 466 | a unique name for the object chosen by the person or 467 | organization creating the participant, names are constructed from 468 | printable ascii characters and must begin with '/' 469 | 470 | :description: 471 | an optional property for describing in human 472 | readable form who or what the object represents 473 | 474 | :creator: 475 | the identifier of the participant who registered the 476 | account object 477 | 478 | :account: 479 | the identifier of the account used to scope the holding 480 | 481 | :asset-type: 482 | the identifier of the asset types 483 | 484 | :instance-count: 485 | the number of instances of the asset being held 486 | 487 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 488 | ExchangeOffer 489 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 490 | 491 | An ExchangeOffer represents an offer to exchange assets or liabilities 492 | of one type for assets or liabilities of another type. Assets or 493 | liabilities are received into an input holding or liability. The ratio 494 | expresses the number of assets to be transferred out for every one that 495 | is transferred in. 496 | 497 | .. code-block:: javascript 498 | 499 | "ExchangeOffer" : 500 | { 501 | "type" : "object", 502 | "properties" : 503 | { 504 | "name" : 505 | { 506 | "type" : "string", 507 | "required" : false 508 | }, 509 | 510 | "description" : 511 | { 512 | "type" : "string", 513 | "required" : false 514 | }, 515 | 516 | "creator" : 517 | { 518 | "type" : "string", 519 | "format" : "IDENTIFIER", 520 | "$ref" : "#Participant", 521 | "required" : true 522 | }, 523 | 524 | "input" : 525 | { 526 | "type" : "string", 527 | "format" : "IDENTIFIER", 528 | "oneOf" : [ 529 | { "$ref" : "#Liability"}, 530 | { "$ref" : "#Holding" } 531 | ], 532 | "required" : true 533 | }, 534 | 535 | "output" : 536 | { 537 | "type" : "string", 538 | "format" : "IDENTIFIER", 539 | "oneOf" : [ 540 | { "$ref" : "#Liability"}, 541 | { "$ref" : "#Holding" } 542 | ], 543 | "required" : true 544 | }, 545 | 546 | "ratio" : 547 | { 548 | "type" : float, 549 | "required" : true 550 | }, 551 | 552 | "minimum" : 553 | { 554 | "type" : int, 555 | "required" : false 556 | }, 557 | 558 | "maximum" : 559 | { 560 | "type" : int, 561 | "required" : false 562 | }, 563 | 564 | "execution" : 565 | { 566 | "type" : "string", 567 | "oneOf" : [ "ExecuteOnce", "ExecuteOncePerParticipant", "Any" ], 568 | "required" : false 569 | } 570 | } 571 | } 572 | 573 | The properties of an ExchangeOffer include: 574 | 575 | :name: 576 | a unique name for the object chosen by the person or 577 | organization creating the participant, names are constructed from 578 | printable ascii characters and must begin with '/' 579 | 580 | :description: 581 | an optional property for describing in human 582 | readable form who or what the object represents 583 | 584 | :creator: 585 | the identifier of the participant who registered the 586 | account object 587 | 588 | :input: 589 | a Holding or Liability into which "payment" is made, this 590 | defines the kind of asset that will be received by the creator of 591 | the offer 592 | 593 | :output: 594 | a Holding or Liability from which goods will be 595 | transferred, this defines the kind of asset that will be given by 596 | the creator of the offer, the creator of the offer must be the 597 | same as the creator of the holding or liability 598 | 599 | :ratio: 600 | the number of instances to transfer from the output 601 | holding for each instance deposited into the input holding 602 | 603 | :minimum: 604 | the smallest number of acceptable instances that can be 605 | transferred into the input holding for the offer to be valid 606 | 607 | :maximum: 608 | the largest number of acceptable instances that can 609 | be transferred into the input holding in one transaction for the 610 | offer to be valid 611 | 612 | :execution: 613 | a modifier that defines additional conditions for 614 | execution of the offer, it may have one of the following values: 615 | 616 | ExecuteOncePerParticipant 617 | the offer may be executed by a participant at most one time 618 | 619 | ExecuteOnce 620 | the offer may be executed at most one time 621 | 622 | Any 623 | the offer may be executed as often as appropriate 624 | 625 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 626 | SellOffer 627 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 628 | 629 | A SellOffer is identical to an ExchangeOffer except that assets must be 630 | transferred out from a Holding. 631 | 632 | .. code-block:: javascript 633 | 634 | "SellOffer" : 635 | { 636 | "type" : "object", 637 | "properties" : 638 | { 639 | "name" : 640 | { 641 | "type" : "string", 642 | "required" : false 643 | }, 644 | 645 | "description" : 646 | { 647 | "type" : "string", 648 | "required" : false 649 | }, 650 | 651 | "creator" : 652 | { 653 | "type" : "string", 654 | "format" : "IDENTIFIER", 655 | "$ref" : "#Participant", 656 | "required" : true 657 | }, 658 | 659 | "input" : 660 | { 661 | "type" : "string", 662 | "format" : "IDENTIFIER", 663 | "oneOf" : [ 664 | { "$ref" : "#Liability"}, 665 | { "$ref" : "#Holding" } 666 | ], 667 | "required" : true 668 | }, 669 | 670 | "output" : 671 | { 672 | "type" : "string", 673 | "format" : "IDENTIFIER", 674 | "$ref" : "#Holding", 675 | "required" : true 676 | }, 677 | 678 | "ratio" : 679 | { 680 | "type" : float, 681 | "required" : true 682 | }, 683 | 684 | "minimum" : 685 | { 686 | "type" : int, 687 | "required" : false 688 | }, 689 | 690 | "maximum" : 691 | { 692 | "type" : int, 693 | "required" : false 694 | }, 695 | 696 | "execution" : 697 | { 698 | "type" : "string", 699 | "oneOf" : [ "ExecuteOnce", "ExecuteOncePerParticipant", "Any" ], 700 | "required" : false 701 | } 702 | } 703 | } 704 | 705 | The properties of a SellOffer include: 706 | 707 | :name: 708 | a unique name for the object chosen by the person or 709 | organization creating the participant, names are constructed from 710 | printable ascii characters and must begin with '/' 711 | 712 | :description: 713 | an optional property for describing in human 714 | readable form who or what the object represents 715 | 716 | :creator: 717 | the identifier of the participant who registered the 718 | account object 719 | 720 | :input: 721 | a Holding or Liability into which "payment" is made, this 722 | defines the kind of asset that will be received by the creator of 723 | the offer 724 | 725 | :output: 726 | a Holding from which goods will be transferred, this 727 | defines the kind of asset that will be given by the creator of the 728 | offer, the creator of the offer must be the same as the creator of 729 | the holding 730 | 731 | :ratio: 732 | the number of instances to transfer from the output 733 | holding for each instance deposited into the input holding 734 | 735 | :minimum: 736 | the smallest number of acceptable instances that can be 737 | transferred into the input holding for the offer to be valid 738 | 739 | :maximum: 740 | the largest number of acceptable instances that can 741 | be transferred into the input holding in one transaction for the 742 | offer to be valid 743 | 744 | :execution: 745 | a modifier that defines additional conditions for 746 | execution of the offer, it may have one of the following values: 747 | 748 | :ExecuteOncePerParticipant: 749 | the offer may be executed by a 750 | participant at most one time 751 | 752 | :ExecuteOnce: 753 | the offer may be executed at most one time 754 | 755 | :Any: 756 | the offer may be executed as often as appropriate 757 | -------------------------------------------------------------------------------- /source/mktplace_developers_guide/mktplace_initial_state.rst: -------------------------------------------------------------------------------- 1 | ----------------------------------------------------------------- 2 | MarketPlace Initial State 3 | ----------------------------------------------------------------- 4 | 5 | The MarketPlace creates several asset types and assets that enable 6 | markets to "bootstrap" participation. All bootstrap asset types and 7 | assets are created by an initial participant with the name 8 | "marketplace". 9 | 10 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11 | Asset Types 12 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13 | 14 | Two asset types are created for bootstrapping: 15 | 16 | - /asset-type/participant -- This is an asset type for creating 17 | participants as an asset, the participant asset type is not 18 | restricted meaning that anyone can create a participant asset 19 | 20 | - /asset-type/token -- This is an asset type for creating the 21 | various token assets used for meta-operations of the market, the 22 | token asset type is restricted meaning that only the marketplace 23 | can create token assets 24 | 25 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 26 | Assets 27 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 28 | 29 | Currently only one asset is created for bootstrapping: 30 | 31 | - /asset/token -- a canonical asset for bootstrap tokens, the asset 32 | is not restricted (meaning that any participant can create a 33 | holding with a token in it), non-consumable (meaning that having a 34 | single token is equivalent to having an infinite number of tokens) 35 | 36 | The token asset is particularly useful for creating "gift" offers that 37 | take tokens as input and give some other asset as output. 38 | -------------------------------------------------------------------------------- /source/mktplace_developers_guide/mktplace_messages.rst: -------------------------------------------------------------------------------- 1 | ----------------------------------------------------------------- 2 | MarketPlace Messages 3 | ----------------------------------------------------------------- 4 | 5 | MarketPlace ledger clients can send messages to validators through an 6 | HTTP/POST interface. Messages are JSON-encoded for example: 7 | 8 | .. code-block:: javascript 9 | 10 | { 11 | "Transaction": { 12 | "Dependencies": [], 13 | "Nonce": 1444777217.496317, 14 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 15 | "TransactionType": "/MarketPlaceTransaction", 16 | "Update": { 17 | "UpdateType": "/mktplace.transactions.ParticipantUpdate/Register" 18 | "Description": "MarketPlace Participant", 19 | "Name": "market", 20 | } 21 | }, 22 | "__NONCE__": 1444777217.575749, 23 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 24 | "__TYPE__": "/mktplace.transactions.MarketPlace/Transaction" 25 | } 26 | 27 | Messages contain one of the :ref:`mktplace-transactions-label` and three 28 | additional fields: 29 | 30 | :__NONCE__: 31 | random float used to ensure the message signature is unique; 32 | we use the python representation of wall clock time 33 | 34 | :__TYPE__: 35 | the type of message; for all MarketPlace transactions the 36 | message type is 37 | "/mktplace.transactions.MarketPlace/Transaction" 38 | 39 | :__SIGNATURE__: 40 | the message signature is computed using all fields in 41 | the message except for the __SIGNATURE__ field. 42 | 43 | -------------------------------------------------------------------------------- /source/mktplace_developers_guide/mktplace_transactions.rst: -------------------------------------------------------------------------------- 1 | .. _mktplace-transactions-label: 2 | 3 | ----------------------------------------------------------------- 4 | MarketPlace Transactions 5 | ----------------------------------------------------------------- 6 | 7 | All MarketPlace transactions have the following fields: 8 | 9 | :Dependencies: 10 | a list of transaction identifiers that must be 11 | committed to the log before this transaction is committed 12 | 13 | :Nonce: 14 | a uniquifier for the transaction, we use a wallclock time 15 | stamp though any float value will suffice; it is the creator of the 16 | transaction that is responsible for choosing a value that will result 17 | in unique signatures. 18 | 19 | :Signature: 20 | the signature of the transaction content only; the 21 | signature of the transaction is computed over the CBOR encoding of 22 | the transaction with keys sorted alphabetically 23 | 24 | :TransactionType: 25 | the name of the transaction family, all MarketPlace 26 | transactions use "/MarketPlaceTransaction" as the TransactionType. 27 | 28 | :Update: 29 | information about the actual change that will be applied to 30 | the MarketPlace ledger. 31 | 32 | 33 | There are no optional fields in MarketPlace transactions. A value must 34 | be specified for every field for the purposes of consistency in 35 | signing. The MarketPlace Client API provides a simple means for filling 36 | in reasonable default values, but other clients must ensure that the 37 | serialized object contains values for all specified fields. 38 | 39 | ----------------------------------------------------------------- 40 | MarketPlace Transaction Updates 41 | ----------------------------------------------------------------- 42 | 43 | The Update object contains an UpdateType field that describes the change 44 | to be applied to the ledger. There are three basic types of updates. The 45 | first to add or remove objects from the ledger: 46 | 47 | :Register: 48 | Create a new object. All register updates have a name and 49 | description field. The name field must be unique for a particular 50 | creator. All updates except the update used to register a new 51 | participant must have a creator field that containts the participant 52 | identifier for the player creating the object. 53 | 54 | :Unregister: 55 | Destroy an existing object. Unregister updates all 56 | contain one field, the object identifier of the object to destroy. 57 | 58 | The final type of update, Exchange, transfers the balance from one 59 | holding/liability object to another through a series of offers. 60 | 61 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 62 | Register Participant 63 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 64 | 65 | .. code-block:: javascript 66 | 67 | "Update" : 68 | { 69 | "UpdateType": "/mktplace.transactions.ParticipantUpdate/Register" 70 | "Description": "MarketPlace Participant", 71 | "Name": "market", 72 | } 73 | 74 | 75 | 76 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 77 | Register Account 78 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 79 | 80 | The fields for account registration include: 81 | 82 | :CreatorID: 83 | the identifier for the participant requesting creation of 84 | the new object 85 | 86 | .. code-block:: javascript 87 | 88 | "Update" : 89 | { 90 | "CreatorID": "1b452fc363a3e024", 91 | "Description": "", 92 | "Name": "/private/account", 93 | "UpdateType": "/mktplace.transactions.AccountUpdate/Register" 94 | } 95 | 96 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 | Register Asset Type 98 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 99 | 100 | The fields for asset type registration include: 101 | 102 | :CreatorID: 103 | The identifier for the participant requesting creation of 104 | the new object 105 | 106 | .. code-block:: javascript 107 | 108 | "Update": 109 | { 110 | "CreatorID": "1b452fc363a3e024", 111 | "Description": "Currency asset type", 112 | "Name": "/asset-type/currency", 113 | "UpdateType": "/mktplace.transactions.AssetTypeUpdate/Register" 114 | } 115 | 116 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 117 | Register Asset 118 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 119 | 120 | The fields for asset registration include: 121 | 122 | :CreatorID: 123 | The identifier for the participant requesting creation of 124 | the new object 125 | 126 | :AssetTypeID: 127 | The identifier for the asset type, the only participant 128 | allowed to create an asset with the type is the participant who 129 | created the type 130 | 131 | 132 | .. code-block:: javascript 133 | 134 | "Update": 135 | { 136 | "AssetTypeID": "77dfddc9936745fc", 137 | "CreatorID": "1b452fc363a3e024", 138 | "Description": "", 139 | "Name": "/asset/currency/mikel", 140 | "UpdateType": "/mktplace.transactions.AssetUpdate/Register" 141 | } 142 | 143 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 144 | Register Holding 145 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 146 | 147 | The fields for holding registration include: 148 | 149 | :CreatorID: 150 | The identifier for the participant requesting creation of 151 | the new object 152 | 153 | :AssetID: 154 | The identifier for the asset stored in the holding 155 | 156 | :Count: 157 | The number of assets stored in the holding 158 | 159 | :AccountID: 160 | The identifier for the account used to manage the holding 161 | 162 | .. code-block:: javascript 163 | 164 | "Update": 165 | { 166 | "AssetID": "b6bdf0368de9855a", 167 | "Count": 1000000, 168 | "CreatorID": "1b452fc363a3e024", 169 | "Description": "", 170 | "Name": "/private/holding/currency/mikel", 171 | "UpdateType": "/mktplace.transactions.HoldingUpdate/Register", 172 | "AccountID": "bb3613256325c35a" 173 | } 174 | 175 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 176 | Register Liability 177 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 178 | 179 | The fields for liability registration include: 180 | 181 | :CreatorID: 182 | The identifier for the participant requesting creation of 183 | the new object 184 | 185 | :AssetTypeID: 186 | The identifier for the asset stored in the holding 187 | 188 | :Count: 189 | The number of assets stored in the holding 190 | 191 | :AccountID: 192 | The identifier for the account used to manage the holding 193 | 194 | :GuarantorID: 195 | The identifier for the participant who guarantees the 196 | liability 197 | 198 | .. code-block:: javascript 199 | 200 | "Update": 201 | { 202 | "AssetTypeID": "b6bdf0368de9855a", 203 | "Count": 1000000, 204 | "GuarantorID": "1b452fc363a3e024", 205 | "CreatorID": "1b452fc363a3e024", 206 | "Description": "", 207 | "Name": "/private/holding/currency/mikel", 208 | "UpdateType": "/mktplace.transactions.LiabilityUpdate/Register", 209 | "AccountID": "bb3613256325c35a" 210 | } 211 | 212 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 213 | Register ExchangeOffer 214 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 215 | 216 | The fields for registration of a SellOffer include: 217 | 218 | :CreatorID: 219 | The identifier for the participant requesting creation of 220 | the new object 221 | 222 | :InputID: 223 | The identifier for the holding (or liability) into which 224 | assets will be transferred (e.g. the holding where payment is 225 | received) 226 | 227 | :OutputID: 228 | The identifier for the holding (or liability) from which 229 | assets will be tranferred (e.g. the holding for assets being 230 | purchased) 231 | 232 | :Ratio: 233 | The number of output assets transferred per input asset 234 | 235 | :Minimum: 236 | the smallest number of acceptable instances that can be 237 | transferred into the input holding for the offer to be valid, 238 | minimum must strictly be smaller than maximum 239 | 240 | :Maximum: 241 | the largest number of acceptable instances that can 242 | be transferred into the input holding in one transaction for the 243 | offer to be valid, maximum must strictly be larger than minimum 244 | 245 | :Execution: 246 | a modifier that defines additional conditions for 247 | execution of the offer, it may have one of the following values: 248 | 249 | :ExecuteOncePerParticipant: 250 | the offer may be executed by a participant at most one time 251 | 252 | :ExecuteOnce: 253 | the offer may be executed at most one time 254 | 255 | :Any: 256 | the offer may be executed as often as appropriate 257 | 258 | .. code-block:: javascript 259 | 260 | "Update": 261 | { 262 | "CreatorID": "5863bd0527ca2143", 263 | "Description": "", 264 | "InputID": "53434b20963cb525", 265 | "Name": "/offer/buyback/bills", 266 | "OutputID": "cc007e32955254a7", 267 | "Ratio": 93, 268 | "Execution": "Any", 269 | "Maximum": 1000000000, 270 | "Minimum": 1, 271 | "UpdateType": "/mktplace.transactions.ExchangeOfferUpdate/Register" 272 | } 273 | 274 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 275 | Register SellOffer 276 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 277 | 278 | The fields for registration of a SellOffer include: 279 | 280 | :CreatorID: 281 | The identifier for the participant requesting creation of 282 | the new object 283 | 284 | :InputID: 285 | The identifier for the holding (or liability) into which 286 | assets will be transferred (e.g. the holding where payment is 287 | received) 288 | 289 | :OutputID: 290 | The identifier for the holding from which assets will be 291 | tranferred (e.g. the holding for assets being purchased) 292 | 293 | :Ratio: 294 | The number of output assets transferred per input asset 295 | 296 | :Minimum: 297 | the smallest number of acceptable instances that can be 298 | transferred into the input holding for the offer to be valid, 299 | minimum must strictly be smaller than maximum 300 | 301 | :Maximum: 302 | the largest number of acceptable instances that can 303 | be transferred into the input holding in one transaction for the 304 | offer to be valid, maximum must strictly be larger than minimum 305 | 306 | :Execution: 307 | a modifier that defines additional conditions for 308 | execution of the offer, it may have one of the following values: 309 | 310 | :ExecuteOncePerParticipant: 311 | the offer may be executed by a participant at most one time 312 | 313 | :ExecuteOnce: 314 | the offer may be executed at most one time 315 | 316 | :Any: 317 | the offer may be executed as often as appropriate 318 | 319 | .. code-block:: javascript 320 | 321 | "Update": 322 | { 323 | "CreatorID": "5863bd0527ca2143", 324 | "Description": "", 325 | "InputID": "53434b20963cb525", 326 | "Name": "/offer/buyback/bills", 327 | "OutputID": "cc007e32955254a7", 328 | "Ratio": 93, 329 | "Execution": "Any", 330 | "Maximum": 1000000000, 331 | "Minimum": 1, 332 | "UpdateType": "/mktplace.transactions.SellOfferUpdate/Register" 333 | } 334 | 335 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 336 | Unregister All Objects 337 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 338 | 339 | The fields used to unregister an object are consistent across all object 340 | types and include: 341 | 342 | :CreatorID: 343 | The identifier for the participant requesting creation of 344 | the new object 345 | 346 | :ObjectID: 347 | The identifier for the object to unregister 348 | 349 | .. code-block:: javascript 350 | 351 | "Update": 352 | { 353 | "CreatorID": "5863bd0527ca2143", 354 | "ObjectID": "ad8d6a71827e9be0", 355 | "UpdateType": "/mktplace.transactions.SellOfferUpdate/Unregister" 356 | } 357 | 358 | 359 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 360 | Exchange 361 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 362 | 363 | The exchange update transfers balances between holdings. The exchange 364 | starts from an initial holding/liability and passes through a specified 365 | series of sell offers until the final transfer is made. Asset types must 366 | be consistent across each transfer. 367 | 368 | :InitialLiabilityID: 369 | the identifier for the initial holding/liability 370 | from which assets are transferred (e.g. from which payment is made) 371 | 372 | :FinalLiabilityID: 373 | the identifier for the holding/liability into which 374 | assets are ultimately transferred (e.g. the holding where goods 375 | purchased are placed) 376 | 377 | :InitialCount: 378 | the number of assets to transfer out of the initial 379 | liability (e.g. the amount paid) 380 | 381 | :OfferIDList: 382 | a list of identifiers for sell offers that will be 383 | applied in order to tranfer assets. 384 | 385 | .. code-block:: javascript 386 | 387 | "Update": 388 | { 389 | "FinalLiabilityID": "8a67d29135306115", 390 | "InitialCount": 10, 391 | "InitialLiabilityID": "84272ffad75a8043", 392 | "OfferIDList": [], 393 | "UpdateType": "/mktplace.transactions.ExchangeUpdate/Exchange" 394 | } 395 | 396 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide.rst: -------------------------------------------------------------------------------- 1 | 2 | ******************************* 3 | Sawtooth Lake Developer's Guide 4 | ******************************* 5 | 6 | .. toctree:: 7 | :maxdepth: 2 8 | 9 | sawtooth_developers_guide/architecture_overview 10 | sawtooth_developers_guide/sawtooth_vagrant 11 | sawtooth_api/modules 12 | sawtooth_developers_guide/web_api/index 13 | sawtooth_developers_guide/validator_network_launcher 14 | sawtooth_developers_guide/workload_simulator 15 | sawtooth_developers_guide/signing_transactions 16 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/architecture_overview.rst: -------------------------------------------------------------------------------- 1 | Architecture Overview 2 | ********************* 3 | 4 | What is the Sawtooth Lake Distributed Ledger? 5 | ============================================= 6 | 7 | The Sawtooth Lake Distributed Ledger is a software framework for 8 | constructing decentralized ledgers with extensible transaction 9 | types. It is comparable to the blockchain ledger that underlies 10 | Bitcoin. Sawtooth Lake uses a unique mechanism for reaching consensus 11 | on the validity of the ledger based on trusted code running inside a 12 | hardware-protected Intel Software Guard Extensions (SGX) enclave. 13 | 14 | One of the initial transaction families supported by Sawtooth Lake is 15 | the MarketPlace. The MarketPlace Transaction Family establishes the 16 | concepts of participants, accounts, assets, holdings, liabilities, 17 | and offers in a decentralized ledger to facilitate the exchange of 18 | digital assets. The Sawtooth Lake architecture allows the definition 19 | of additional transaction families or the consumption of an existing 20 | asset-type agnostic transaction family (like MarketPlace) to meet 21 | domain-specific needs. 22 | 23 | Repository Structure 24 | ==================== 25 | 26 | **sawtooth-core** - This repository contains the core functionaliy 27 | of the distributed ledger, including: 28 | 29 | * the gossip networking layer 30 | * basic transaction, block, and message objects 31 | * the base journal implementation 32 | * the PoET and quorum voting journal consensus mechanisms 33 | * 'built-in' transaction families - Endpoint Registry and Integer Key 34 | Registry 35 | 36 | **sawtooth-mktplace** - This repository contains the MarketPlace 37 | Transaction Family. This demonstrates how to inherit and extend base 38 | sawtooth-core object types to implement a custom transaction family. 39 | sawtooth-mktplace also includes a command line interface called 40 | *mktclient* for interacting with validators running the MarketPlace 41 | Transaction Family. 42 | 43 | **sawtooth-validator** - This repository contains the implementation 44 | of a server, known as the validator. The validator acts as a node on 45 | the gossip network, as defined by sawtooth-core. Validators exchange 46 | and act upon messages, as defined by the core classes and via 47 | additional plug-in transaction families like the MarketPlace 48 | Transaction Family. 49 | 50 | Core Architecture 51 | ================= 52 | 53 | The Sawtooth Lake Distributed Ledger consists of three major 54 | architectural layers: the Ledger layer, the Journal layer, and the 55 | Communication Layer. 56 | 57 | 58 | .. image:: ../images/arch_overview_layers.* 59 | :scale: 50 % 60 | :align: center 61 | 62 | Ledgers 63 | ------- 64 | 65 | Ledgers are a conceptual semantic and data model layer for 66 | transaction types. Ledgers are described as a 'conceptual' layer 67 | because they are implemented as a specialization of existing base 68 | classes already present in the Communication and Journal layers. 69 | 70 | .. image:: ../images/arch_overview_ledger.* 71 | :scale: 50 % 72 | :align: center 73 | 74 | In addition to some in-built system ledgers (Endpoint Registry, and 75 | Integer Key Registry), implementing new classes in the ledger layer 76 | allows for the creation of new transaction families. The MarketPlace 77 | Transaction Family, located in the sawtooth-mktplace repository, is a 78 | good example of how the ledger layer can be extended. 79 | 80 | Journals 81 | -------- 82 | 83 | A journal handles consensus on blocks of identifiers. Identifiers 84 | reference transactions, which are globally replicated. In order to 85 | confirm blocks, nodes need a copy of the transaction. In this fashion, 86 | the journal provides global consensus on block ordering, transaction 87 | ordering within blocks, and the content of transactions. 88 | 89 | .. image:: ../images/arch_overview_journal.* 90 | 91 | The journal module in sawtooth-core contains: 92 | 93 | * the implementation of the base transaction and transaction block classes 94 | * the consensus algorithms 95 | * the global store manager 96 | * the block store and key value store 97 | 98 | The consensus journal object is journal.journal_core.Journal in the 99 | sawtooth-core repository. 100 | 101 | Consensus Mechanisms 102 | ~~~~~~~~~~~~~~~~~~~~ 103 | 104 | Sawtooth Lake contains two consensus implementations: PoET and Quorum 105 | Voting. 106 | 107 | PoET and SGX 108 | :::::::::::: 109 | 110 | The Sawtooth Lake Distributed Ledger provides a unique mechanism to 111 | ensure fairness in the node lottery. Instead of a Proof-of-Work 112 | competition amongst nodes, Sawtooth Lake implements a 113 | Proof-of-Elapsed-Time (PoET) algorithm for distributed consensus. 114 | PoET relies upon a trusted execution environment, Intel's Software 115 | Guard Extensions (SGX), to generate fair, verifiable random wait 116 | timers and signed certificates of timer expiration. This mechanism 117 | substantially reduces the computation and energy cost of ensuring 118 | fair distributed consensus. 119 | 120 | The implementation of PoET in Sawtooth Lake runs in a simulated enclave, 121 | not a true trusted execution environment. For this reason, attestation 122 | that wait timers have been fairly generated is not possible. This 123 | version of PoET is intended for experimental purposes and should not 124 | be used as the consensus mechanism in any 'production' environment. 125 | 126 | The PoET implementation is located in journal.consensus.poet in 127 | sawtooth-core. 128 | 129 | Quorum Voting 130 | ::::::::::::: 131 | 132 | The Quorum Voting consensus implementation is an adaptation of the 133 | Ripple [#]_ and Stellar [#]_ consensus protocols. 134 | 135 | .. [#] The Ripple Consensus Protocol - 136 | https://ripple.com/files/ripple_consensus_whitepaper.pdf 137 | .. [#] The Stellar Consensus Protocol - 138 | https://www.stellar.org/papers/stellar-consensus-protocol.pdf 139 | 140 | The Quorum Voting implementation is located in 141 | journal.consensus.quorum in sawtooth-core. 142 | 143 | Transactions 144 | ~~~~~~~~~~~~ 145 | 146 | A transaction is a set of updates to be applied atomically to a 147 | ledger. The transaction defines the data model and representation. 148 | For example, in the IntegerKey Transaction Family (located in 149 | ledger.transaction.integer_key in sawtooth-core), the 150 | IntegerKeyTransaction is defined as a list of zero or more updates 151 | to key value pairs using the defined verbs 'set', 'inc', and 'dec'. 152 | The associated IntegerKeyTransactionMessage wraps the derived 153 | transaction object in a standard message object. There is typically 154 | a message type for every transaction type. 155 | 156 | Blocks 157 | ~~~~~~ 158 | 159 | A block is a set of transactions to be applied to a ledger. Other 160 | than some specialized transaction block implementations for the 161 | consensus mechanisms, new transaction block types are not typically 162 | created. The expectation is that multiple transaction types will 163 | coexist on single transaction blocks of type 164 | journal.transaction_block.TransactionBlock. There is typically a 165 | message type for every transaction block type. 166 | 167 | Communication 168 | ------------- 169 | 170 | The gossip protocol enables communication between nodes. It includes 171 | protocol level connection management and basic flow control on top 172 | of UDP. A Token Bucket [#]_ implementation is used to limit the average 173 | rate of message transmission. 174 | 175 | .. [#] https://en.wikipedia.org/wiki/Token_bucket 176 | 177 | .. image:: ../images/arch_overview_communication.* 178 | 179 | Peers in the gossip network are called Nodes. Nodes exchange Messages. 180 | Message handling upon arrival is dispatched via EventHandlers 181 | associated with the journal. 182 | 183 | Messages 184 | ~~~~~~~~ 185 | 186 | Messages represent information to send or receive from peers over the 187 | gossip network. Messages are serialized and deserialized using a 188 | standard wire format (either CBOR or JSON). 189 | 190 | Message types include: 191 | 192 | * transaction messages 193 | * transaction block messages 194 | * journal transfer messages 195 | * debug messages (log data) 196 | * connection messages 197 | * shutdown messages 198 | * topology messages 199 | 200 | Messages are used broadly across the architecture for both system 201 | communication (administrative messages, consensus messages), and for 202 | transaction-type specific handling. 203 | 204 | Transaction Family Plugin Architecture 205 | ====================================== 206 | 207 | As mentioned above, the creation of new classes in the conceptual 208 | 'ledger' layer allows for the addition of transaction families. Via 209 | a message handling and dispatch model, new transaction families can 210 | register themselves with the underlying journal consensus and global 211 | store mechanisms to allow for arbitrary callbacks on message arrival 212 | and persistence of the transactions. 213 | 214 | If specialized transaction stores are required, those can also be 215 | defined and added to the ledger during initialization (via 216 | register_transaction_types). 217 | 218 | In order to create a basic transaction family, implement the following: 219 | 220 | .. code-block:: python 221 | 222 | def register_transaction_types(ledger) 223 | 224 | Register message handlers for defined message types and add a 225 | transaction store to the ledger for the transaction types. 226 | 227 | .. code-block:: python 228 | 229 | class BasicTransactionMessage(transaction_message.TransactionMessage) 230 | 231 | implement __init__ 232 | 233 | .. code-block:: python 234 | 235 | class BasicTransaction(transaction.Transaction) 236 | 237 | implement __init__, __str__, is_valid, apply, and dump 238 | 239 | Refer to ledger.transaction.integer_key in sawtooth-core for a 240 | simple example, or to mktplace.transactions.market_place in 241 | sawtooth-mktplace for a more substantial example. 242 | 243 | Transaction Families are loaded into the validator in sawtooth-validator 244 | via the "TransactionFamilies" config value (see 245 | sawtooth-validator/etc/txnvalidator.js). 246 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/sawtooth_vagrant.rst: -------------------------------------------------------------------------------- 1 | 2 | Vagrant 3 | ======= 4 | 5 | Overview 6 | -------- 7 | 8 | Vagrant is a tool which installs and configures virtual development 9 | environments. It allows development teams to easily specify and share 10 | consistent virtual machine configurations. 11 | 12 | The sawtooth-dev-tools repository contains a Vagrant configuration which 13 | is specifically tailored to Sawtooth development. A new developer with 14 | installed copies of Vagrant and VirtualBox can clone the sawtooth-dev-tools 15 | repository and have a functional VM which can run validators within a few 16 | minutes. 17 | 18 | A quick introduction to using sawtooth-dev-tools is available as a 19 | quickstart in this Developer's Guide. 20 | 21 | Layout of the sawtooth-dev-tools git Repository 22 | ------------------------------------------------ 23 | 24 | The sawtooth-dev-tools repository is structured as follows: 25 | 26 | .. code-block:: console 27 | 28 | sawtooth-dev-tools/ 29 | bootstrap.d/ 30 | guest-files/ 31 | plugins/ 32 | scripts/ 33 | tests/ 34 | win-bin/ 35 | Vagrantfile 36 | 37 | 38 | Vagrantfile 39 | Vagrantfile is the main configuration file for Vagrant. It is ruby 40 | code executed by Vagrant and is executed every ime a vagrant command is 41 | executed. 42 | 43 | bootstrap.d 44 | The bootstrap.d directory contains a set of bash scripts which are 45 | executed in order during the provisioning step of 'vagrant up'. These 46 | scripts are always executed. 47 | 48 | guest-files 49 | The guest-files directory contains configuration files which are used by 50 | the bootstrap.d scripts. 51 | 52 | There is also a local-env.sh script which contains environment specific 53 | variables for Sawtooth development, such as PYTHONPATH. 54 | 55 | plugins 56 | The plugins directory contains bash scripts which can be easily configured 57 | to execute during the provisioning step of 'vagrant up'. These scripts 58 | run after bootstrap.d scripts. 59 | 60 | scripts 61 | This scripts directory contains scripts which are sometimes useful to the 62 | developer after provisioning has been completed and the developer has a 63 | shell in the virtual machine. For example, there are scripts which 64 | help build Ubuntu packages. 65 | 66 | tests 67 | The tests directory includes tests run within the Vagrant environment. These are 68 | in addition to the unit and integration tests found in the tests directory of 69 | sawtooth-core, sawtooth-validator and sawtooth-mktplace. 70 | 71 | win-bin 72 | The win-bin directory includes scripts for running Sawtooth natively 73 | under Windows and is not used in the Vagrant environment. 74 | 75 | 76 | Layout in the Virtual Machine 77 | ----------------------------- 78 | 79 | A convenient feature of Vagrant is the easy sharing of directories between 80 | the host machine and the guest virtual machine. By default the Vagrant 81 | configuration directory is mounted under /vagrant in the virtual machine. 82 | 83 | In the sawtooth-dev-tools configuration a /project mount point is also 84 | defined which provides access to the Sawtooth repositories. 85 | 86 | Configuration Options 87 | --------------------- 88 | 89 | There is a rudimentary configuration system in place which can impact 90 | how the Vagrant environment is provisioned. 91 | 92 | The files involved are: 93 | 94 | .. code-block:: console 95 | 96 | conf-defaults.sh 97 | conf-local.sh 98 | conf-local.sh.example 99 | 100 | The conf-local.sh file, which is not checked into the git repository, 101 | is the one that should be modified locally. This file can be 102 | initialized by copying conf-local.sh.example to conf-local.sh. 103 | 104 | The conf-default.sh file defines the defaults for configuration 105 | values which are not set. 106 | 107 | The valid config values are: 108 | 109 | INSTALL_TYPE 110 | By default, this is set to 'none'. It can be set to one of: 111 | 112 | * none - do not install anything by default 113 | * setup.py - build and install sawtooth-core, sawtooth-validator, 114 | sawtooth-mktplace from the git repositories using 'python setup.py install' 115 | * deb - build and install sawtooth-core, sawtooth-validator, sawtooth-mktplace from 116 | the git repositories by first creating deb packages and then installing 117 | those deb packages. 118 | 119 | START_TXNVALIDATOR 120 | By default, this is set to 'no'. If set to 'yes', then txnvalidator 121 | will be started with upstart or systemd. For this option to work, 122 | INSTALL_TYPE must be set to 'deb'. 123 | 124 | PLUGINS 125 | By default, set to "build_ubuntu_deps install_ubuntu_deps install_sphinx". 126 | Specify a space-separated list of plugins to run. The plugins are contained 127 | in the plugins directory. 128 | 129 | The following plugins are available: 130 | 131 | build_ubuntu_deps 132 | This plugin builds the debian packages for cbor, colorlog, and 133 | pybitcointools. They are placed in /project/build/packages/. 134 | 135 | install_latex 136 | This plugin installs Latex, which is required for building a PDF of the 137 | documentation. This is disabled by default because it takes a fairly 138 | long time to download. 139 | 140 | install_ubuntu_deps 141 | This plugin installs the debian packages built by build_ubuntu_deps. 142 | 143 | install_sphinx 144 | This plugin installs sphinx, which is required for building the sawtooth 145 | documentation. 146 | 147 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/signing_transactions.rst: -------------------------------------------------------------------------------- 1 | ----------------------------------------------------------------- 2 | Signing Transactions 3 | ----------------------------------------------------------------- 4 | 5 | Consistency in transaction signing is critical for successful submission 6 | of transactions to Sawtooth Lake. 7 | 8 | **Step 1: Serialize the transaction** 9 | 10 | The transaction schema describes the fields that must be present in the 11 | serialized transaction. All fields, including optional fields, must have a 12 | value set. For optional fields that are not specified, the value of the 13 | field must be set to the default value specified in the schema. 14 | 15 | The exception to the previous rule is that the top level "Signature" 16 | field must be removed from the transaction completely. It is not 17 | sufficient simply to set the value to an empty string. 18 | 19 | An important note is that data types must match those used in the 20 | schema. Specifically, a float must have at least one decimal point or 21 | the value will be encoded as an integer. For example, for signing 22 | purposes, 1.0 is not equivalent to 1. 23 | 24 | All strings in the transaction including fields names and values should 25 | be encoded as Unicode. 26 | 27 | Fields in the transaction must be ordered alpha-numerically by field 28 | name. This includes field in any contained object. 29 | 30 | The transaction is serialized in `CBOR `. 31 | 32 | **Step 2: Create the signature for the serialized transaction** 33 | 34 | The resulting serialized document is signed with the transactors private 35 | ECDSA key using the secp256k1 curve. 36 | 37 | The signature uses a `DER encoding 38 | ` similar to `Bitcoin 39 | ` and 40 | OpenSSL. 41 | 42 | **Step 3: Add the signature to the transaction** 43 | 44 | Set the value of the "Signature" field to the base64 encoded signature. 45 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/validator_network_launcher.rst: -------------------------------------------------------------------------------- 1 | ****************************** 2 | The Validator Network Launcher 3 | ****************************** 4 | 5 | Overview 6 | -------- 7 | 8 | If you wish to start up a validator network with multiple instances of 9 | txnvalidator, but do not want to either bring up multiple virtual machine 10 | instances or use separate physical machines, there is a script that simplifies 11 | the process for running multiple instances of txnvalidator on a single virtual 12 | machine instance. As in the single txnvalidator case, you will need to log in 13 | to the development environment (i.e., ``vagrant ssh``). In its simplest form, 14 | the script is executed as follows: 15 | 16 | .. code-block:: console 17 | 18 | $ cd /project/sawtooth-validator 19 | $ ./bin/launcher 20 | No config file specified, loading /project/sawtooth-validator/etc/txnvalidator.js 21 | Overriding the following keys from validator configuration file: /project/sawtooth-validator/etc/txnvalidator.js 22 | NodeName 23 | Host 24 | HttpPort 25 | Port 26 | LogFile 27 | LogLevel 28 | KeyFile 29 | GenesisLedger 30 | Configuration: 31 | { 'config': '/project/sawtooth-validator/etc/txnvalidator.js', 32 | 'count': 1, 33 | 'data_dir': '/tmp/tmpohtWIM', 34 | 'data_dir_is_tmp': True, 35 | 'load_blockchain': None, 36 | 'log_level': 'WARNING', 37 | 'save_blockchain': None, 38 | 'validator': '/project/sawtooth-validator/bin/txnvalidator', 39 | 'validator_config': { u'CertificateSampleLength': 30, 40 | u'InitialWaitTime': 750.0, 41 | u'LedgerType': u'lottery', 42 | u'LedgerURL': u'http://localhost:8800/', 43 | 'LogLevel': 'WARNING', 44 | u'MaxTransactionsPerBlock': 1000, 45 | u'MinTransactionsPerBlock': 1, 46 | u'NetworkBurstRate': 128000, 47 | u'NetworkDelayRange': [0.0, 0.1], 48 | u'NetworkFlowRate': 96000, 49 | u'Restore': False, 50 | u'TargetConnectivity': 3, 51 | u'TargetWaitTime': 30.0, 52 | u'TopologyAlgorithm': u'RandomWalk', 53 | u'TransactionFamilies': [ u'ledger.transaction.integer_key', 54 | u'sawtooth_xo'], 55 | u'UseFixedDelay': True}} 56 | Launching initial validator: .......... 10.08S 57 | Launching validator network: 0.00S 58 | Waiting for validator registration: . 1.12S 59 | 60 | Without any command-line options, the script launches a single txnvalidator 61 | instance. As can be seen from the output above, the launcher reports the 62 | configuration file used, usually 63 | /project/sawtooth-validator/etc/txnvalidator.js, as well as any configuration 64 | settings that it has overridden. 65 | 66 | After the script launches the txnvalidator instance(s), it presents an 67 | interactive shell command-line interface: 68 | 69 | .. code-block:: console 70 | 71 | Welcome to the sawtooth txnvalidator network manager interactive console 72 | launcher_cli.py> 73 | 74 | Command-Line Options 75 | -------------------- 76 | 77 | The launcher has numerous command-line options, all of which can be seen by 78 | executing the command with the ``--help`` (or ``-h``) command-line option. 79 | 80 | .. code-block:: console 81 | 82 | $ ./bin/launcher --help 83 | 84 | usage: launcher [-h] [--validator VALIDATOR] [--config CONFIG] [--count COUNT] 85 | [--save-blockchain SAVE_BLOCKCHAIN] 86 | [--load-blockchain LOAD_BLOCKCHAIN] [--data-dir DATA_DIR] 87 | [--log-level LOG_LEVEL] 88 | 89 | optional arguments: 90 | -h, --help show this help message and exit 91 | --validator VALIDATOR 92 | Fully qualified path to the txnvalidator to run 93 | --config CONFIG Base validator config file 94 | --count COUNT Number of validators to launch 95 | --save-blockchain SAVE_BLOCKCHAIN 96 | Save the blockchain to a file when the network is 97 | shutdown. This is the name of the tar.gz file that the 98 | blockchain will be saved in. 99 | --load-blockchain LOAD_BLOCKCHAIN 100 | load an existing blockchain from file. This is a file 101 | name that points to a tar.gz that was generated from a 102 | previous run using the --save-blockchain option. 103 | --data-dir DATA_DIR Where to store the logs, data, etc for the network 104 | --log-level LOG_LEVEL 105 | LogLevel to run the validators at. 106 | 107 | To initially launch, for example, two txnvalidator instances and have the 108 | logging level set to DEBUG, execute the following: 109 | 110 | .. code-block:: console 111 | 112 | $ ./bin/launcher --count 2 --log-level DEBUG 113 | 114 | .. note:: 115 | 116 | By default, the log files will be located in a temporary directory in /tmp, 117 | with each txnvalidator instance having its own log file. 118 | 119 | Obtaining Help About Available Commands 120 | --------------------------------------- 121 | 122 | Execute the ``help`` command to learn about the commands available via the 123 | command-line interface. 124 | 125 | .. code-block:: console 126 | 127 | launcher_cli.py> help 128 | 129 | Documented commands (type help ): 130 | ======================================== 131 | config exit help launch launch_cmd status 132 | 133 | Undocumented commands: 134 | ====================== 135 | EOF err kill log out 136 | 137 | As the help command indicates, you can learn more about a specific command by 138 | executing ``help ``. 139 | 140 | Retrieving the Status of the Validator Network 141 | ---------------------------------------------- 142 | 143 | Execute the ``status`` command to get information about the running 144 | txnvalidator instances. 145 | 146 | .. code-block:: console 147 | 148 | launcher_cli.py> status 149 | 0: pid:8827 log: 18.77 KB 150 | 1: pid:8831 log: 19.23 KB 151 | 152 | Based upon the initial execution of the script with an instance count of two 153 | and the log level set to DEBUG, the ``status`` command, as expected, presents 154 | information about two txnvalidator instances. For each txnvalidator instance, 155 | the following information is presented: 156 | 157 | * Instance ID, which is used for all commands that are specific to a txnvalidator instance 158 | * Process ID 159 | * Log file size 160 | 161 | Adding a Validator to the Validator Network 162 | ------------------------------------------- 163 | 164 | To add another txnvalidator instance to the existing validator network, execute 165 | the ``launch`` command. When the status command is run, there are now three 166 | txnvalidator instances. 167 | 168 | .. code-block:: console 169 | 170 | launcher_cli.py> launch 171 | Validator validator-2 launched. 172 | launcher_cli.py> status 173 | 0: pid:8827 log: 31.71 KB 174 | 1: pid:8831 log: 30.31 KB 175 | 2: pid:8959 log: 16.76 KB 176 | 177 | Retrieving a Validator's Configuration 178 | -------------------------------------- 179 | 180 | To see the configuration information for the txnvalidator instance that was 181 | just launched to, for example, get the HTTP port it is listening on, execute 182 | the ``config`` command, providing the txnvalidator instance ID. 183 | 184 | .. code-block:: console 185 | 186 | launcher_cli.py> config 2 187 | { 188 | "NodeName": "validator-2", 189 | "TransactionFamilies": ["ledger.transaction.integer_key", "sawtooth_xo"], 190 | "TargetConnectivity": 3, 191 | "TargetWaitTime": 30.0, 192 | "GenesisLedger": false, 193 | "HttpPort": 8802, 194 | "id": 2, 195 | "LogFile": "/tmp/tmpylbmp_/validator-2.log", 196 | "MaxTransactionsPerBlock": 1000, 197 | "NetworkFlowRate": 96000, 198 | "CertificateSampleLength": 30, 199 | "Restore": false, 200 | "InitialWaitTime": 750.0, 201 | "DataDirectory": "/tmp/tmpylbmp_", 202 | "LogLevel": "DEBUG", 203 | "LedgerType": "lottery", 204 | "UseFixedDelay": true, 205 | "Host": "localhost", 206 | "LedgerURL": "http://localhost:8800", 207 | "NetworkBurstRate": 128000, 208 | "NetworkDelayRange": [0.0, 0.1], 209 | "AdministrationNode": "1EQFYqvMRLpjTjL5Bv3vSAMrZdnRY6e5uk", 210 | "MinTransactionsPerBlock": 1, 211 | "KeyFile": "/tmp/tmp4K9qEd/validator-2.wif", 212 | "Port": 8902, 213 | "TopologyAlgorithm": "RandomWalk" 214 | } 215 | 216 | As can be seen from the configuration information above, the newly-launched 217 | txnvalidator instance is listening on port 8802. 218 | 219 | Viewing a Validator's Log File 220 | ------------------------------ 221 | 222 | To view the log file for a txnvalidator instance, navigate to the data 223 | directory, which can either be specified as a command-line parameter to the 224 | script, or can be obtained by executing the config command for a particular 225 | txnvalidator instance. Alternatively, execute the ``log`` command for a 226 | particular txnvalidator instance: 227 | 228 | .. code-block:: console 229 | 230 | launcher_cli.py> log 2 231 | [21:10:14, 10, validator_cli] CONFIG: TransactionFamilies = ['ledger.transaction.integer_key', 'sawtooth_xo'] 232 | [21:10:14, 10, validator_cli] CONFIG: TargetConnectivity = 3 233 | 234 | [21:10:14, 20, connect_message] received connect confirmation from node validator-0 235 | [21:10:14, 20, node] enabling node 16rgLPPvsGdbCkanmfWnXo8RQxjKVYyHoQ 236 | [21:10:15, 10, gossip_core] clean up processing 1 unacked packets 237 | 238 | Removing a Validator from the Validator Network 239 | ----------------------------------------------- 240 | 241 | To remove a txnvalidator instance from the validator network, execute the 242 | ``kill`` command, providing its instance ID. For example, to remove the 243 | txnvalidator instance that was just launched, execute the following: 244 | 245 | .. code-block:: console 246 | 247 | launcher_cli.py> kill 2 248 | Validator validator-2 killed. 249 | 250 | Tearing Down the Validator Network 251 | ---------------------------------- 252 | 253 | To tear down the validator network, execute the ``exit`` command. It will take 254 | care of stopping each of the txnvalidator instances as well as cleaning up any 255 | temporary files/directories that were created. 256 | 257 | .. code-block:: console 258 | 259 | launcher_cli.py> exit 260 | Sending shutdown message to validators: : ... 0.04S 261 | Giving validators time to shutdown: : .......... 10.02S 262 | Killing 2 intransigent validators: : ... 0.00S 263 | Cleaning temp data store /tmp/tmpylbmp_ 264 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/block.rst: -------------------------------------------------------------------------------- 1 | .. _block-label: 2 | 3 | ================================================================= 4 | /block 5 | ================================================================= 6 | 7 | 8 | Block IDs are always ordered from the newest committed block ID to the oldest. 9 | 10 | .. http:get:: /block 11 | 12 | Returns a list of the committed block IDs. 13 | 14 | :query blockcount: The maximum number of blocks to return. 15 | 16 | .. http:get:: /block/{block_id} 17 | 18 | Returns the contents of block `block_id`. 19 | 20 | .. http:get:: /block/{block_id}/{key} 21 | 22 | Returns the value associated with key `key` within block `block_id`. 23 | 24 | 25 | 26 | **Example request**: 27 | 28 | .. sourcecode:: http 29 | 30 | GET /block HTTP/1.1 31 | Host: localhost:8800 32 | User-Agent: curl/7.43.0 33 | Accept: */* 34 | 35 | 36 | **Example response**: 37 | 38 | .. sourcecode:: http 39 | 40 | HTTP/1.1 200 OK 41 | Date: Fri, 19 Feb 2016 18:16:40 GMT 42 | Content-Length: 128 43 | Content-Type: application/json 44 | 45 | [ 46 | "efaa886dc6b5b325", 47 | "4238a27a967a0cdb", 48 | "85ec88be3fdd404b", 49 | "b7351fa8d5a49dcf", 50 | "20c3a8dbffdd8c74", 51 | "3e15ef3909d2452e" 52 | ] 53 | 54 | **Example**: 55 | 56 | .. sourcecode:: console 57 | 58 | GET /block?blockcount=2 59 | 60 | .. sourcecode:: javascript 61 | 62 | [ 63 | "efaa886dc6b5b325", 64 | "4238a27a967a0cdb" 65 | ] 66 | 67 | **Example**: 68 | 69 | .. sourcecode:: console 70 | 71 | GET /block/85ec88be3fdd404b 72 | 73 | .. sourcecode:: javascript 74 | 75 | { 76 | "Identifier": "85ec88be3fdd404b", 77 | "PreviousBlockID": "b7351fa8d5a49dcf", 78 | "Signature": "GyZOrdAA2212HYyKGvKlHBnkPAqOKY1XeQoIbsI6/4wDhY26FdffXLOgUpDMhpQhSKKwtGQBQL0uzpwcypKqbjQ=", 79 | "TransactionBlockType": "/Lottery/PoetTransactionBlock", 80 | "TransactionIDs": [ 81 | "0102098777664ea4", 82 | "3c5f74a72486eedf", 83 | "fada0f0b22123857", 84 | "b3c5bd4cabf45a5b" 85 | ], 86 | "WaitCertificate": { 87 | "GlobalSignature": "3jqbnsfeyn7iwfkajwbvvkwfemy2525vtci42vakjgifhejy7t2a8mpeg7kykjrn9reiq443xpvzvqh7c2e4r7fgn5cvtnbvb7w42ts", 88 | "SerializedCert": "{ \"Duration\": 43.434298, \"LocalMean\": 37.200000, \"MinimumWaitTime\": 0.000000, \"PreviousBlockID\": \"b7351fa8d5a49dcf\", \"RequestTime\": 1455905328.460869 }" 89 | } 90 | } 91 | 92 | **Example**: 93 | 94 | .. sourcecode:: console 95 | 96 | GET /block/b33ce9f5d203bfc0/Signature 97 | 98 | 99 | .. sourcecode:: javascript 100 | 101 | "HHMDpz0uFKXCQ6DcOx5WYW+fXHm6TeQTN9TNHhprn8djSUashJDI9IhI0xNFH3a1mfeDREskxRRE80dn1pb8V7Y=" 102 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/echo.rst: -------------------------------------------------------------------------------- 1 | ================================================================= 2 | /echo 3 | ================================================================= 4 | 5 | 6 | .. http:post:: /echo 7 | 8 | The request is parsed into an object, re-serialized to JSON, and returned in the response. 9 | 10 | 11 | **Example request**: 12 | 13 | .. sourcecode:: http 14 | 15 | POST /echo HTTP/1.1 16 | Host: localhost:8800 17 | User-Agent: curl/7.43.0 18 | Accept: */* 19 | Content-Type: application/json 20 | Content-Length: 536 21 | 22 | { 23 | "Transaction": { 24 | "Dependencies": [], 25 | "Nonce": 1444777217.496317, 26 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 27 | "TransactionType": "/MarketPlaceTransaction", 28 | "Update": { 29 | "UpdateType": "/mktplace.transactions.ParticipantUpdate/Register", 30 | "Description": "MarketPlaceParticipant", 31 | "Name": "market" 32 | } 33 | }, 34 | "__NONCE__": 1444777217.575749, 35 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 36 | "__TYPE__": "/mktplace.transactions.MarketPlace/Transaction" 37 | } 38 | 39 | 40 | **Example response**: 41 | 42 | .. sourcecode:: http 43 | 44 | HTTP/1.1 200 OK 45 | Date: Mon, 22 Feb 2016 05:35:31 GMT 46 | Content-Length: 557 47 | Content-Type: application/json 48 | 49 | { 50 | "Transaction": { 51 | "Dependencies": [], 52 | "Nonce": 1444777217.496317, 53 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 54 | "TransactionType": "/MarketPlaceTransaction", 55 | "Update": { 56 | "Description": "MarketPlaceParticipant", 57 | "Name": "market", 58 | "UpdateType": "/mktplace.transactions.ParticipantUpdate/Register" 59 | } 60 | }, 61 | "__NONCE__": 1444777217.575749, 62 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 63 | "__TYPE__": "/mktplace.transactions.MarketPlace/Transaction" 64 | } -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/forward.rst: -------------------------------------------------------------------------------- 1 | ================================================================= 2 | /forward 3 | ================================================================= 4 | 5 | 6 | .. http:post:: /forward 7 | 8 | Forwards the message to each of the validator's peers. 9 | 10 | 11 | **Example request**: 12 | 13 | .. sourcecode:: http 14 | 15 | POST /forward HTTP/1.1 16 | Host: localhost:8800 17 | User-Agent: curl/7.43.0 18 | Accept: */* 19 | Content-Type: application/json 20 | Content-Length: 536 21 | 22 | { 23 | "Transaction": { 24 | "Dependencies": [], 25 | "Nonce": 1444777217.496317, 26 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 27 | "TransactionType": "/MarketPlaceTransaction", 28 | "Update": { 29 | "UpdateType": "/mktplace.transactions.participant_update/Register", 30 | "Description": "MarketPlaceParticipant", 31 | "Name": "market" 32 | } 33 | }, 34 | "__NONCE__": 1444777217.575749, 35 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 36 | "__TYPE__": "/mktplace.transactions.MarketPlace/Transaction" 37 | } 38 | 39 | 40 | **Example response**: 41 | 42 | .. sourcecode:: http 43 | 44 | HTTP/1.1 200 OK 45 | Date: Mon, 22 Feb 2016 05:35:31 GMT 46 | Content-Length: 557 47 | Content-Type: application/json 48 | 49 | { 50 | "Transaction": { 51 | "Dependencies": [], 52 | "Nonce": 1444777217.496317, 53 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 54 | "TransactionType": "/MarketPlaceTransaction", 55 | "Update": { 56 | "Description": "MarketPlaceParticipant", 57 | "Name": "market", 58 | "UpdateType": "/mktplace.transactions.participant_update/Register" 59 | } 60 | }, 61 | "__NONCE__": 1444777217.575749, 62 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 63 | "__TYPE__": "/mktplace.transactions.market_place/Transaction" 64 | } -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/index.rst: -------------------------------------------------------------------------------- 1 | .. _web-api-index-label: 2 | 3 | ************************** 4 | Distributed Ledger Web API 5 | ************************** 6 | 7 | A validator supports a Web API allowing for access to blocks, transactions 8 | and state storage. It also enables sending transactions to the network. 9 | 10 | For the query APIs, if the `Accept` header is "application/cbor", 11 | the response will be encoded using `CBOR `_. 12 | If the `Accept` header is missing or has any other value, 13 | the response will be encoded using `JSON `_. 14 | 15 | If the response is encoded using JSON, the response can be "pretty printed" 16 | by adding a "p" parameter to the URL, for example: 17 | 18 | .. http:get:: /block?p=1 19 | 20 | Returns a list of the committed block IDs, which will be pretty-printed 21 | if the response is encoded in JSON. 22 | 23 | .. note:: 24 | 25 | The example responses given in this 26 | document are pretty printed even without the "p" query parameter 27 | for clarity. 28 | 29 | Contents: 30 | 31 | .. toctree:: 32 | :maxdepth: 2 33 | 34 | store 35 | block 36 | transaction 37 | initiate 38 | forward 39 | echo 40 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/initiate.rst: -------------------------------------------------------------------------------- 1 | ================================================================= 2 | /initiate 3 | ================================================================= 4 | 5 | 6 | .. http:post:: /initiate 7 | 8 | Signs a messages and sends it to the validator's peers. 9 | The request must come from the host where the validator is running. 10 | 11 | 12 | **Example request**: 13 | 14 | .. sourcecode:: http 15 | 16 | POST /initiate HTTP/1.1 17 | Host: localhost:8800 18 | User-Agent: curl/7.43.0 19 | Accept: */* 20 | Content-Type: application/json 21 | Content-Length: 536 22 | 23 | { 24 | "Dependencies": [], 25 | "Nonce": 1444777217.496317, 26 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 27 | "TransactionType": "/MarketPlaceTransaction", 28 | "Update": { 29 | "UpdateType": "/mktplace.transactions.participant_update/Register", 30 | "Description": "MarketPlaceParticipant", 31 | "Name": "market" 32 | } 33 | } 34 | 35 | 36 | **Example response**: 37 | 38 | .. sourcecode:: http 39 | 40 | HTTP/1.1 200 OK 41 | Date: Mon, 22 Feb 2016 05:35:31 GMT 42 | Content-Length: 557 43 | Content-Type: application/json 44 | 45 | { 46 | "Transaction": { 47 | "Dependencies": [], 48 | "Nonce": 1444777217.496317, 49 | "Signature": "HAy35m01U0SNVbCBDUS+EQ8ufC1x7d1V2IAwRRqDQX4UhdKr3YMIiiHCTLLPrRCbyDB1jpiaemfDNoznqvd1eS4=", 50 | "TransactionType": "/MarketPlaceTransaction", 51 | "Update": { 52 | "Description": "MarketPlaceParticipant", 53 | "Name": "market", 54 | "UpdateType": "/mktplace.transactions.participant_update/Register" 55 | } 56 | }, 57 | "__NONCE__": 1444777217.575749, 58 | "__SIGNATURE__": "HAFYXv9paHt/EQ35vQeR/TPbm48/maA0lKAav/u7kkl4womFuDh8emJRowoO0dHLfUEJO4NzlwxY3FpdwA9hDa4=", 59 | "__TYPE__": "/mktplace.transactions.market_place/Transaction" 60 | } -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/store.rst: -------------------------------------------------------------------------------- 1 | ================================================================= 2 | /store 3 | ================================================================= 4 | 5 | .. http:get:: /store 6 | 7 | Returns a list of all of the store names. 8 | 9 | .. http:get:: /store/{tf_name} 10 | 11 | Returns a list of keys within `tf_name`. The "tf" is short for Transaction 12 | Family. 13 | 14 | .. http:get:: /store/{tf_name}/* 15 | 16 | Returns a dump of all the keys and values within `tf_name`. 17 | 18 | .. http:get:: /store/{tf_name}/{key} 19 | 20 | Returns the value associated with key `key` within store `tf_name`. 21 | 22 | :query blockid: Uses the version of the store resulting from the commitment 23 | of block `blockid`. When omitted, defaults to the version 24 | of the store associated with the last committed block. 25 | 26 | **Example request**: 27 | 28 | .. sourcecode:: http 29 | 30 | GET /store HTTP/1.1 31 | Host: localhost:8800 32 | User-Agent: curl/7.43.0 33 | Accept: */* 34 | 35 | 36 | **Example response**: 37 | 38 | .. sourcecode:: http 39 | 40 | HTTP/1.1 200 OK 41 | Date: Fri, 19 Feb 2016 02:34:33 GMT 42 | Content-Length: 85 43 | Content-Type: application/json 44 | 45 | [ 46 | "/IntegerKeyTransaction", 47 | "/EndpointRegistryTransaction", 48 | "/MarketPlaceTransaction" 49 | ] 50 | 51 | 52 | **Example**: 53 | 54 | .. sourcecode:: console 55 | 56 | GET /store/IntegerKeyTransaction 57 | 58 | .. sourcecode:: javascript 59 | 60 | [ 61 | "SYM3", 62 | "SYM2", 63 | "SYM1", 64 | "SYM0" 65 | ] 66 | 67 | **Example**: 68 | 69 | .. sourcecode:: console 70 | 71 | GET /store/IntegerKeyTransaction/* 72 | 73 | .. sourcecode:: javascript 74 | 75 | { 76 | "SYM0": 5, 77 | "SYM1": 4, 78 | "SYM2": 1, 79 | "SYM3": 2 80 | } 81 | 82 | 83 | **Example**: 84 | 85 | .. sourcecode:: console 86 | 87 | GET /store/IntegerKeyTransaction/SYM1 88 | 89 | .. sourcecode:: javascript 90 | 91 | 4 92 | 93 | **Example**: 94 | 95 | .. sourcecode:: console 96 | 97 | GET /store/IntegerKeyTransaction/*?blockid=1f8fc8250cd26fb3 98 | 99 | .. sourcecode:: javascript 100 | 101 | {"SYM0": 0} 102 | 103 | Note that after block `1f8fc8250cd26fb3` was committed, the 104 | `IntegerKeyTransaction` store only contained the SYM0 key. The "SYM1", 105 | "SYM2" and "SYM3" keys were added in later blocks. 106 | 107 | .. note:: 108 | 109 | The block id was obtained by using the block API (see :ref:`block-label`). 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/web_api/transaction.rst: -------------------------------------------------------------------------------- 1 | ================================================================= 2 | /transaction 3 | ================================================================= 4 | 5 | 6 | Transaction IDs are always ordered from the newest committed transaction ID 7 | to the oldest. 8 | 9 | .. http:get:: /transaction 10 | 11 | Returns a list of the committed transaction IDs. 12 | 13 | :query blockcount: Returns the transaction IDs from up to 14 | `blockcount` blocks. 15 | 16 | .. http:get:: /transaction/{transaction_id} 17 | 18 | Returns the contents of transaction `transaction_id`. 19 | 20 | .. http:head:: /transaction/{transaction_id} 21 | 22 | The HTTP response code indicates the status of transaction `transaction_id`. 23 | 24 | :statuscode 200: The transaction exists and has been committed. 25 | :statuscode 302: The transaction exists but has not been committed. 26 | :statuscode 404: The transaction does not exist. 27 | 28 | .. http:get:: /transaction/{transaction_id}/{key} 29 | 30 | Returns the value associated with key `key` within transaction 31 | `transaction_id`. 32 | 33 | 34 | **Example request**: 35 | 36 | .. sourcecode:: http 37 | 38 | GET /transaction HTTP/1.1 39 | Host: localhost:8800 40 | User-Agent: curl/7.43.0 41 | Accept: */* 42 | 43 | **Example response**: 44 | 45 | .. sourcecode:: http 46 | 47 | HTTP/1.1 200 OK 48 | Date: Fri, 19 Feb 2016 19:29:29 GMT 49 | Content-Length: 317 50 | Content-Type: application/json 51 | 52 | [ 53 | "7d0cb57cdaa34ee0", 54 | "6f747d9cb173921f", 55 | "87fdf8ee10bee691", 56 | "9a403d328f2da810", 57 | "74048866a4983941", 58 | "01eee862b6a10ebc", 59 | "1e79d167c62bbc44", 60 | "d422d8793210714f", 61 | "1f48c06a715c8e11", 62 | "70931019ed499b2e", 63 | "f74872b90cbf5e7f", 64 | "92c5bdc786e90e1b", 65 | "91e5e24562e45c33", 66 | "6e6f0bc13ffb4b61", 67 | "c6d2c9bd05fd648d" 68 | ] 69 | 70 | 71 | **Example**: 72 | 73 | .. sourcecode:: console 74 | 75 | GET /transaction?blockcount=1 76 | 77 | .. sourcecode:: javascript 78 | 79 | [ 80 | "92c5bdc786e90e1b", 81 | "91e5e24562e45c33", 82 | "6e6f0bc13ffb4b61", 83 | "c6d2c9bd05fd648d" 84 | ] 85 | 86 | **Example**: 87 | 88 | .. sourcecode:: http 89 | 90 | HEAD /transaction/1e79d167c62bbc44 HTTP/1.1 91 | Host: localhost:8800 92 | User-Agent: curl/7.43.0 93 | Accept: */* 94 | 95 | .. sourcecode:: http 96 | 97 | HTTP/1.1 200 OK 98 | Date: Fri, 19 Feb 2016 19:34:37 GMT 99 | 100 | 101 | **Example**: 102 | 103 | .. sourcecode:: console 104 | 105 | GET /transaction/1e79d167c62bbc44 106 | 107 | 108 | .. sourcecode:: javascript 109 | 110 | { 111 | "Dependencies": [], 112 | "Identifier": "1e79d167c62bbc44", 113 | "InBlock": "32ec280dab040d00", 114 | "Nonce": 1455906424.223023, 115 | "Signature": "HAHOQuBLeMy7tAKnOHfSepg2pPBSwDrJRKWTXj4Znuy3Hbgq1VcvA23odR1b2RU27ssTVLksCDcVOod+z8408yg=", 116 | "Status": 2, 117 | "TransactionType": "/IntegerKeyTransaction", 118 | "Updates": [ 119 | { 120 | "Name": "SYM1", 121 | "Value": 0, 122 | "Verb": "set" 123 | } 124 | ] 125 | } 126 | 127 | **Example**: 128 | 129 | .. sourcecode:: console 130 | 131 | GET /transaction/1e79d167c62bbc44/InBlock 132 | 133 | .. sourcecode:: javascript 134 | 135 | "32ec280dab040d00" 136 | -------------------------------------------------------------------------------- /source/sawtooth_developers_guide/workload_simulator.rst: -------------------------------------------------------------------------------- 1 | ********************** 2 | The Workload Simulator 3 | ********************** 4 | 5 | Overview 6 | -------- 7 | 8 | Sawtooth Lake has a workload simulator that can be used to generate a 9 | synthetic transaction workload. The workload simulator attempts to generate 10 | transactions at a relatively steady rate across the network of validators 11 | it has discovered, adapting to validators joining and leaving the network. 12 | In its simplest form, the workload simulator is started as follows: 13 | 14 | .. code-block:: console 15 | 16 | $ cd /project/sawtooth-core 17 | $ ./bin/simulator 18 | [22:35:28 INFO simulator_cli] Simulator configuration: 19 | [22:35:28 INFO simulator_cli] Simulator: url = http://127.0.0.1:8800 20 | [22:35:28 INFO simulator_cli] Simulator: workload = txnintegration.integer_key_workload.IntegerKeyWorkload 21 | [22:35:28 INFO simulator_cli] Simulator: rate = 12 22 | [22:35:28 INFO simulator_cli] Simulator: discover = 15 23 | [22:35:28 INFO simulator_cli] Simulator: verbose = 1 24 | [22:35:28 INFO simulator] Discovered a new validator: http://127.0.0.1:8800 25 | [22:35:28 INFO simulator] Discovered a new validator: http://127.0.0.1:8803 26 | [22:35:28 INFO simulator] Discovered a new validator: http://127.0.0.1:8801 27 | [22:35:28 INFO simulator] Discovered a new validator: http://127.0.0.1:8804 28 | [22:35:28 INFO simulator] Discovered a new validator: http://127.0.0.1:8802 29 | [22:35:28 INFO simulator] Simulator will generate 12 transaction(s)/minute 30 | [22:35:28 INFO simulator] Simulator will discover validators every 15 minute(s) 31 | 32 | Without any command-line options, the workload simulator attempts to load the 33 | configuration file that controls execution from 34 | ``/.sawtooth/simulator.cfg``. If the file does not exist, the 35 | workload simulator will create it and populate it with the defaults shown 36 | above. 37 | 38 | Configuration File 39 | ------------------ 40 | 41 | An example configuration file is as follows: 42 | 43 | .. code-block:: none 44 | 45 | [Simulator] 46 | url = http://127.0.0.1:8800 47 | workload = txnintegration.integer_key_workload.IntegerKeyWorkload 48 | rate = 12 49 | discover = 15 50 | verbose = 1 51 | 52 | The Simulator section of the configuration file contains name/value pairs that 53 | are used to control the execution of the workload simulator. The names in the 54 | name/value pairs correspond directly to command-line options that share the 55 | same name. If a command-line option has one or more dashes in it, the 56 | corresponding configuration file option name will replace the dashes with 57 | underscores. The configuration file options are: 58 | 59 | * ``url`` The URL of the initial validator used to prime the simulator. The 60 | simulator will begin with this validator's endpoint registry to discover 61 | the validators in the validator network and then for each new validator 62 | discovered will fetch its endpoint registry and will keep doing this until 63 | it has discovered all of the validators in the validator network. If this 64 | option is not present in the configuration file, the default is 65 | \http://127.0.0.1:8800. 66 | * ``workload`` The workload generator that will be used to generate 67 | transactions. This is specified as module_name.class_name. If this option 68 | is not present in the configuration file, the default is 69 | txnintegration.integer_key_workload.IntegerKeyWorkload. 70 | * ``rate`` The rate, in transactions per minute, that the workload simulator 71 | will attempt to generate transactions. If this option is not present in the 72 | configuration file, the default is 12 transactions per minute. 73 | * ``discover`` How often, in minutes, that the workload simulator will check 74 | for changes in the validator network. If this options is not present in the 75 | configuration file, the default is once every 15 minutes. 76 | * ``verbose`` The verbosity level for workload simulator logging messages 77 | that are displayed on the console. Verbosity values correspond to the 78 | following: 79 | 80 | * 0: display messages with logging level of WARNING and above 81 | * 1: display messages with logging level of INFO and above 82 | * >= 2: display messages with logging level of DEBUG and above 83 | 84 | If this options is not present in the configuration file, the default 85 | verbosity level is 1. 86 | 87 | .. note:: 88 | 89 | Individual transaction workloads may also have their own sections that 90 | contain values. 91 | 92 | 93 | Command-Line Options 94 | -------------------- 95 | 96 | The workload simulator has numerous command-line options, all of which can be 97 | seen by executing the command with the ``--help`` (or ``-h``) command-line 98 | option. 99 | 100 | .. note:: 101 | 102 | Any options provided on the command-line override their corresponding 103 | entries in the configuration file or defaults for options that do not 104 | appear in the configuration file. 105 | 106 | .. code-block:: console 107 | 108 | $ ./bin/simulator --help 109 | usage: simulator [-h] [--url] [--workload WORKLOAD] [--rate RATE] 110 | [--discover DISCOVER] [--config CONFIG] [-v] 111 | 112 | optional arguments: 113 | -h, --help show this help message and exit 114 | --url Base validator URL 115 | --workload WORKLOAD Transaction workload 116 | --rate RATE Transaction rate in transactions per minute 117 | --discover DISCOVER How often, in minutes, to refresh validators list 118 | --config CONFIG Config file to provide base configuration for the 119 | simulator and (possibly) the workload generator. 120 | Command-line options override corresponding values in 121 | the configuration file 122 | -v, --verbose enable more verbose output 123 | 124 | The verbosity of the workload simulator is controlled by the number of 125 | occurrences of the ``--verbose`` (or ``-v``) option. The number of occurrences 126 | directly correspond to the numeric value described above for the ``verbose`` 127 | configuration file option. For example, ``-vv``, ``-v -v``, and 128 | ``--verbose --verbose`` all would result in logging messages with level 129 | DEBUG and above being displayed on the console. 130 | 131 | The ``--config CONFIG`` option is used to specify the configuration file to 132 | use in place of the default one. 133 | 134 | The remaining command-line options correspond directly to their counterparts 135 | in the configuration file. 136 | 137 | -------------------------------------------------------------------------------- /source/sysadmin_guide.rst: -------------------------------------------------------------------------------- 1 | 2 | **************************** 3 | System Administrator's Guide 4 | **************************** 5 | 6 | .. toctree:: 7 | :maxdepth: 2 8 | 9 | sysadmin_guide/packaging_ubuntu 10 | sysadmin_guide/packaging_sles 11 | sysadmin_guide/packaging_windows 12 | sysadmin_guide/installation_ubuntu 13 | sysadmin_guide/installation_sles 14 | sysadmin_guide/installation_windows 15 | sysadmin_guide/network_configuration 16 | 17 | -------------------------------------------------------------------------------- /source/sysadmin_guide/installation_sles.rst: -------------------------------------------------------------------------------- 1 | 2 | ******************** 3 | Installation on SLES 4 | ******************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To install onto SLES, you need the following: 10 | 11 | * SLES 12 12 | * SawtoothLake Distribution (sawtoothlake-x.y.z-sles-packages.tar.gz) 13 | 14 | Configure Zypper 15 | ================ 16 | 17 | Two additional repositories are required for installation. To configure them, run: 18 | 19 | .. code-block:: console 20 | 21 | root@sles # zypper addrepo \ 22 | http://download.opensuse.org/repositories/devel:libraries:c_c++/SLE_12/devel:libraries:c_c++.repo 23 | root@sles # zypper addrepo \ 24 | http://download.opensuse.org/repositories/devel:languages:python/SLE_12/devel:languages:python.repo 25 | root@sles # zypper refresh 26 | 27 | SawtoothLake Installation 28 | ========================= 29 | 30 | As root, unpack the SawtoothLake Distribution: 31 | 32 | .. code-block:: console 33 | 34 | root@sles # tar xvfj sawtoothlake-x.y.z-sles-packages.tar.bz2 35 | 36 | Install the SawtoothLake RPM files: 37 | 38 | .. code-block:: console 39 | 40 | root@sles # cd sawtoothlake-x.y.z-sles-packages 41 | root@sles # zypper install -y *.rpm 42 | 43 | 44 | Starting and Stopping the Validator 45 | =================================== 46 | 47 | The validator is run via systemd and can be started and stopped with systemctl 48 | commands. 49 | 50 | To start the validator: 51 | 52 | .. code-block:: console 53 | 54 | root@ubuntu # systemctl start sawtooth-validator 55 | 56 | To stop the validator: 57 | 58 | .. code-block:: console 59 | 60 | root@ubuntu # systemctl stop sawtooth-validator 61 | 62 | You can also view the Upstart status with: 63 | 64 | .. code-block:: console 65 | 66 | root@ubuntu # systemctl status sawtooth-validator 67 | 68 | The process name will be 'txnvalidator' and you can verify it is running 69 | with ps: 70 | 71 | .. code-block:: console 72 | 73 | root@ubuntu # ps -ef | grep txnvalidator 74 | 75 | Configuring the Validator 76 | ========================= 77 | 78 | When run via systemd, the txnvalidator options can be changed in 79 | /etc/sysconfig/sawtooth-validator with the TXNVALIDATOR_OPTIONS environment 80 | variable. This includes specifying which configuration file the 81 | txnvalidator should use. 82 | 83 | Configuration files are placed in /etc/sawtooth-validator. 84 | 85 | By default, the validator will start up as a 'base' validator. 86 | It will not reach out to other validator nodes, and it will initialize 87 | a new set of data files in the data directory, /var/lib/sawtooth-validator 88 | by default. 89 | 90 | In order to join the new validator to an existing network of validators, 91 | the "LedgerURL" setting must be changed in the configuration file to 92 | point to a valid URL for an existing http validator in the network. 93 | 94 | .. code-block:: none 95 | 96 | { 97 | "HttpPort" : 0, 98 | "Host" : "localhost", 99 | "Port" : 0, 100 | "NodeName" : "node000", 101 | "LedgerURL" : "http://base-validator.domain.com:8800/", 102 | 103 | 104 | It is also important to set the "NodeName" value to a unique value based 105 | on your naming convention. The node's key, which must be generated using 106 | txnkeygen, must be named {node name}.wif and placed in the keys directory. 107 | 108 | Several other settings are important for correct functionality of the 109 | new validator node. The configuration file must contain the list of 110 | valid transaction families supported by the validator network. 111 | 112 | .. code-block:: none 113 | 114 | "TransactionFamilies" : [ 115 | "IntegerKey", 116 | "MarketPlace" 117 | ] 118 | 119 | Lastly, the "AdministrationNode" setting must contain the address of the 120 | administration node on the validator network. This instructs the validator 121 | to listen for and act on administrative transactions (like shutdown) 122 | received from the administration node. The administration node address 123 | can be found in the keys directory on the adminstration node in a file 124 | called {node name}.addr. 125 | 126 | .. code-block:: none 127 | 128 | "AdministrationNode" : "19ns29kWDTX8vNeHNzJbJy6S9HZiqHZyEE" 129 | 130 | Log Files 131 | ========= 132 | 133 | The primary directory for log files is /var/log/sawtooth-validator. In 134 | addition, stdout and stderr are captured and viewable with journalctl. 135 | 136 | .. code-block:: console 137 | 138 | root@ubuntu # journalctl -u sawtooth-validator 139 | 140 | -------------------------------------------------------------------------------- /source/sysadmin_guide/installation_ubuntu.rst: -------------------------------------------------------------------------------- 1 | 2 | ********************** 3 | Installation on Ubuntu 4 | ********************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To install onto Ubuntu, you need the following: 10 | 11 | * Ubuntu 14.04 LTS 12 | * SawtoothLake Distribution (sawtoothlake-x.y.z-ubuntu-packages.tar.gz) 13 | 14 | Dependency Installation 15 | ======================= 16 | 17 | Apply all Ubuntu updates: 18 | 19 | .. code-block:: console 20 | 21 | root@ubuntu # apt-get update -y 22 | 23 | As root, install the necessary dependecies with apt-get: 24 | 25 | .. code-block:: console 26 | 27 | root@ubuntu # apt-get install -y -q \ 28 | python-twisted \ 29 | python-twisted-web \ 30 | libjson0 \ 31 | libcrypto++ 32 | 33 | SawtoothLake Installation 34 | ========================= 35 | 36 | As root, unpack the SawtoothLake Distribution: 37 | 38 | .. code-block:: console 39 | 40 | root@ubuntu # tar xvfj sawtoothlake-x.y.z-ubuntu-packages.tar.bz2 41 | 42 | Install the SawtoothLake .deb files: 43 | 44 | .. code-block:: console 45 | 46 | root@ubuntu # cd sawtoothlake-x.y.z-ubuntu-packages 47 | root@ubuntu # dpkg -i *.deb 48 | 49 | Starting and Stopping the Validator 50 | =================================== 51 | 52 | The validator is run via Upstart and can be started and stopped with Upstart 53 | commands. 54 | 55 | To start the validator: 56 | 57 | .. code-block:: console 58 | 59 | root@ubuntu # start sawtooth-validator 60 | 61 | To stop the validator: 62 | 63 | .. code-block:: console 64 | 65 | root@ubuntu # stop sawtooth-validator 66 | 67 | You can also view the Upstart status with: 68 | 69 | .. code-block:: console 70 | 71 | root@ubuntu # status sawtooth-validator 72 | 73 | The process name will be 'txnvalidator' and you can verify it is running 74 | with ps: 75 | 76 | .. code-block:: console 77 | 78 | root@ubuntu # ps -ef | grep txnvalidator 79 | 80 | Configuring the Validator 81 | ========================= 82 | 83 | When run via upstart, the txnvalidator options can be changed in 84 | /etc/defaults/sawtooth-validator with the TXNVALIDATOR_OPTIONS environment 85 | variable. This includes specifying which configuration file the 86 | txnvalidator should use. 87 | 88 | Configuration files are placed in /etc/sawtooth-validator. 89 | 90 | By default, the validator will start up as a 'base' validator. 91 | It will not reach out to other validator nodes, and it will initialize 92 | a new set of data files in the data directory, /var/lib/sawtooth-validator 93 | by default. 94 | 95 | In order to join the new validator to an existing network of validators, 96 | the "LedgerURL" setting must be changed in the configuration file to 97 | point to a valid URL for an existing http validator in the network. 98 | 99 | .. code-block:: none 100 | 101 | { 102 | "HttpPort" : 0, 103 | "Host" : "localhost", 104 | "Port" : 0, 105 | "NodeName" : "node000", 106 | "LedgerURL" : "http://base-validator.domain.com:8800/", 107 | 108 | It is also important to set the "NodeName" value to a unique value based 109 | on your naming convention. The node's key, which must be generated using 110 | txnkeygen, must be named {node name}.wif and placed in the keys directory. 111 | 112 | Several other settings are important for correct functionality of the 113 | new validator node. The configuration file must contain the list of 114 | valid transaction families supported by the validator network. 115 | 116 | .. code-block:: none 117 | 118 | "TransactionFamilies" : [ 119 | "IntegerKey", 120 | "MarketPlace" 121 | ] 122 | 123 | Lastly, the "AdministrationNode" setting must contain the address of the 124 | administration node on the validator network. This instructs the validator 125 | to listen for and act on administrative transactions (like shutdown) 126 | received from the administration node. The administration node address 127 | can be found in the keys directory on the adminstration node in a file 128 | called {node name}.addr. 129 | 130 | .. code-block:: none 131 | 132 | "AdministrationNode" : "19ns29kWDTX8vNeHNzJbJy6S9HZiqHZyEE" 133 | 134 | Log Files 135 | ========= 136 | 137 | The primary directory for log files is /var/log/sawtooth-validator. In 138 | addition, Upstart captures stdout and stderr and redirects them to 139 | /var/log/upstart/sawtooth-validator.log. 140 | 141 | -------------------------------------------------------------------------------- /source/sysadmin_guide/installation_windows.rst: -------------------------------------------------------------------------------- 1 | 2 | *********************** 3 | Installation on Windows 4 | *********************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To run the SawtoothLake Validator you will need the following: 10 | 11 | * Sawtooth-validator.exe 12 | * Python 2.7.11 Windows x86-64 MSI Installer (python-2.7.11.amd64.msi) 13 | * Python Extensions for Windows exe installer (pywin32-219.win-amd64-py2.7.exe) 14 | 15 | .. note:: 16 | 17 | Python Extensions for Windows is only necessary if you intend to run 18 | SawtoothLake Validator as a Windows service. 19 | 20 | Download Python Windows x86-64 MSI Installer (python-2.7.11.amd64.msi) from: 21 | 22 | https://www.python.org/downloads/windows/ 23 | 24 | Download Python Extensions for Windows (pywin32-219.win-amd64-py2.7.exe) from: 25 | 26 | http://sourceforge.net/projects/pywin32/files/pywin32/ 27 | 28 | Install Tools 29 | ============= 30 | 31 | Install Python 32 | -------------- 33 | 34 | Navigate to the directory where you saved python-2.7.11.amd64.msi 35 | and double click it to start the installer. 36 | 37 | .. image:: ../images/python_all_users.* 38 | 39 | * Make sure "Install for all Users" is selected and then click Next > 40 | 41 | .. image:: ../images/python_default_path.* 42 | 43 | * Accept the default path of ``C:\Python27`` by clicking Next > 44 | 45 | .. image:: ../images/python_customize.* 46 | 47 | * We don't need any customizations here. Click Next > 48 | 49 | .. image:: ../images/python_progress_bar.* 50 | 51 | * A progress bar will appear 52 | 53 | .. image:: ../images/python_complete.* 54 | 55 | * The install is complete! Click Finish. 56 | 57 | Install Dependencies 58 | -------------------- 59 | 60 | We'll need to install a few Python packages using pip. 61 | 62 | Open a Powershell window and run the following commmands: 63 | 64 | .. code-block:: console 65 | 66 | PS C:\Users\username> c:\python27\scripts\pip.exe install cbor 67 | PS C:\Users\username> c:\python27\scripts\pip.exe install colorlog 68 | PS C:\Users\username> c:\python27\scripts\pip.exe install ecdsa 69 | PS C:\Users\username> c:\python27\scripts\pip.exe install pybitcointools 70 | PS C:\Users\username> c:\python27\scripts\pip.exe install twisted 71 | 72 | 73 | Install Validator 74 | ================= 75 | 76 | You can install SawtoothLake Validator either using the GUI or with an 77 | unattended command line mode. We'll cover both below. 78 | 79 | GUI Install 80 | ----------- 81 | 82 | .. image:: ../images/validator_download_folder.* 83 | 84 | * Navigate to the folder containing sawtooth-validator.exe 85 | 86 | .. image:: ../images/validator_progress_bar.* 87 | 88 | * Double click sawtooth-validator.exe and a window will appear with a 89 | progress bar 90 | 91 | * Click close once the installer finishes 92 | 93 | Command Line Install 94 | -------------------- 95 | 96 | Open Powershell, navigate to the folder containing sawtooth-validator.exe and 97 | start the install 98 | 99 | .. code-block:: console 100 | 101 | PS C:\Users\username> cd .\Downloads 102 | PS C:\Users\username\Downloads> .\sawtooth-validator.exe /S 103 | 104 | 105 | Whichever way you chose to install, you should now see the Validator 106 | files have been placed in ``C:\Program Files (x86)\Intel\sawtooth-validator``. 107 | 108 | .. image:: ../images/validator_files.* 109 | 110 | Install As a Service 111 | -------------------- 112 | 113 | Install the Validator code using either the GUI or command line options above. 114 | 115 | * After the install is complete, open a Powershell window and set some 116 | system environment variables: 117 | 118 | .. code-block:: console 119 | 120 | PS C:\Users\username> [Environment]::SetEnvironmentVariable("Path",$Env:Path + ";c:\python27;", "Machine") 121 | PS C:\Users\username> [Environment]::SetEnvironmentVariable("PYTHONPATH", "C:\Program Files (x86)\Intel\sawtooth-validator\lib\python\", "Machine") 122 | 123 | * Rename txnvalidator so Python Extensions can import it: 124 | 125 | .. code-block:: console 126 | 127 | PS C:\Users\username> cd "C:\Program Files (x86)\Intel\sawtooth-validator\bin" 128 | PS C:\Program Files (x86)\Intel\sawtooth-validator\bin> mv .\txnvalidator .\txnvalidator.py 129 | 130 | * Install the Validator sevice: 131 | 132 | .. code-block:: console 133 | 134 | PS C:\Program Files (x86)\Intel\sawtooth-validator\bin> python.exe .\txnvalidator.py install 135 | Installing service SawtoothValidator-Service 136 | Service installed 137 | 138 | * Open the Windows services console to verify that the service was installed successfully. 139 | 140 | .. code-block:: console 141 | 142 | PS C:\Program Files (x86)\Intel\sawtooth-validator\bin> services.msc 143 | 144 | .. image:: ../images/services_console.* 145 | 146 | 147 | Run Validator 148 | ============= 149 | 150 | The PYTHONPATH environment variable needs to set and the the Python directory 151 | needs to be added to our path before running Validator. Open 152 | Powershell and run the following: 153 | 154 | .. code-block:: console 155 | 156 | PS C:\Users\username> $env:PYTHONPATH += ";C:\Program Files (x86)\Intel\sawtooth-validator\lib\python\" 157 | PS C:\Users\username> $env:PATH += ";c:\python27;" 158 | 159 | Start txnvalidator by navigating to ``C:\Program Files (x86)\Intel\sawtooth-validator\bin`` 160 | and running: 161 | 162 | .. code-block:: console 163 | 164 | PS C:\Users\username> cd "C:\Program Files (x86)\Intel\sawtooth-validator\bin" 165 | PS C:\Program Files (x86)\Intel\sawtooth-validator\bin> python .\txnvalidator --config simple.js --url **none** 166 | 167 | You should see the logfiles being updated in 168 | ``C:\Program Files (x86)\Intel\sawtooth-validator\logs``. 169 | 170 | .. image:: ../images/logfile.* 171 | 172 | As a Service 173 | ------------ 174 | 175 | In order to run Validator as a Windows service a few changes need to be made 176 | to the config files. 177 | 178 | .. code-block:: console 179 | 180 | PS C:\Users\username> cd "C:\Program Files (x86)\Intel\sawtooth-validator\conf" 181 | PS C:\Program Files (x86)\Intel\sawtooth-validator\conf> mv .\simple.js .\settings.js 182 | 183 | Open settings.js in your preferred editor and change the "LedgerURL" value to 184 | "\*\*none\*\*": 185 | 186 | .. code-block:: none 187 | 188 | { 189 | "HttpPort" : 0, 190 | "Host" : "localhost", 191 | "Port" : 0, 192 | "NodeName" : "base000", 193 | "LedgerURL" : "**none**", 194 | 195 | The service is set to Manual start by default. Run the below command to start 196 | it: 197 | 198 | .. code-block:: console 199 | 200 | PS C:\Users\username> Start-Service SawtoothValidator-Service 201 | 202 | Configure Validator 203 | =================== 204 | 205 | By default, the validator will start up as a 'base' validator. 206 | It will not reach out to other validator nodes, and it will initialize 207 | a new set of data files in the data directory, 208 | `C:\\Program Files (x86)\\Intel\\sawtooth-validator\\data\\` 209 | by default. 210 | 211 | In order to join the new validator to an existing network of validators, 212 | the "LedgerURL" setting must be changed in the configuration file to 213 | point to a valid URL for an existing http validator in the network. 214 | 215 | .. code-block:: none 216 | 217 | { 218 | "HttpPort" : 0, 219 | "Host" : "localhost", 220 | "Port" : 0, 221 | "NodeName" : "node000", 222 | "LedgerURL" : "http://base-validator.domain.com:8800/", 223 | 224 | It is also important to set the "NodeName" value to a unique value based 225 | on your naming convention. The node's key, which must be generated using 226 | txnkeygen, must be named {node name}.wif and placed in the keys directory. 227 | 228 | Several other settings are important for correct functionality of the 229 | new validator node. The configuration file must contain the list of 230 | valid transaction families supported by the validator network. 231 | 232 | .. code-block:: none 233 | 234 | "TransactionFamilies" : [ 235 | "IntegerKey", 236 | "MarketPlace" 237 | ] 238 | 239 | Lastly, the "AdministrationNode" setting must contain the address of the 240 | administration node on the validator network. This instructs the validator 241 | to listen for and act on administrative transactions (like shutdown) 242 | received from the administration node. The administration node address 243 | can be found in the keys directory on the adminstration node in a file 244 | called {node name}.addr. 245 | 246 | .. code-block:: none 247 | 248 | "AdministrationNode" : "19ns29kWDTX8vNeHNzJbJy6S9HZiqHZyEE" 249 | 250 | Uninstallation 251 | ============== 252 | 253 | Just like with installation, SawtoothLake Validator can be uninstalled 254 | either using the GUI or with an unattended command line mode. 255 | 256 | .. note:: 257 | 258 | If you installed SawtoothLake Validator as a service, please run the 259 | service removal commands below before running uninstall.exe 260 | 261 | GUI Uninstall 262 | ------------- 263 | 264 | .. image:: ../images/control_panel.* 265 | 266 | * Open the Control Panel and select "Uninstall a Program" 267 | 268 | .. image:: ../images/add_remove.* 269 | 270 | * Once the Programs and Features Window appears, double click 271 | "Intel - sawtoothvalidator - Sawtooth" 272 | 273 | .. image:: ../images/validator_uninstall_progress_bar.* 274 | 275 | * Click close once the uninstaller finishes 276 | 277 | Command Line Uninstall 278 | ---------------------- 279 | 280 | * Open Powershell, navigate to the folder containing uninstaller.exe and 281 | start the install: 282 | 283 | .. code-block:: console 284 | 285 | PS C:\Users\username> cd 'C:\Program Files (x86)\Intel\sawtooth-validator' 286 | PS C:\Program Files (x86)\Intel\sawtooth-validator> .\uninstall.exe /S 287 | 288 | However you chose to uninstall, you should now see the Validator 289 | files have been removed from ``C:\Program Files (x86)\Intel\sawtooth-validator``. 290 | 291 | You may see some remaining directories. The uninstaller chooses not to remove 292 | the ``conf``, ``data``, or ``logs`` directories if they aren't empty. You can back up any 293 | remaining files and remove the leftover directories by hand. 294 | 295 | Service removal 296 | --------------- 297 | 298 | .. code-block:: console 299 | 300 | PS C:\Program Files (x86)\Intel\sawtooth-validator\bin> python.exe .\txnvalidator.py remove 301 | Removing service SawtoothValidator-Service 302 | Service removed 303 | -------------------------------------------------------------------------------- /source/sysadmin_guide/network_configuration.rst: -------------------------------------------------------------------------------- 1 | ********************* 2 | Network Configuration 3 | ********************* 4 | 5 | Validators 6 | ========== 7 | 8 | Sawtooth Lake uses two ports, one TCP, one UDP, to communicate with other 9 | members of a validator network. You may need to modify some firewall rules 10 | to facilitate this traffic. Because the validator software assumes complete 11 | connectivity to the other nodes in the network, if you intend to participate 12 | in a Sawtooth Lake network over the internet, each validator will need a 13 | publically routable IP address. NAT is not currently supported. 14 | 15 | Primarily, traffic between validator nodes takes place over UDP. By default 16 | Sawtooth Lake selects a random high UDP port for communication. You can choose 17 | a static port to use by changing the "Port" value from "0" to any unused UDP 18 | port. We recommend using 5500. Your firewall rules should be configured to 19 | allow both ingress and egress from all networks for this port. 20 | 21 | The validator nodes listen on TCP port 8800 for communication from clients. 22 | This port is adjustable via the config file value "HttpPort", though changing 23 | this requires additional client configuration. Firewall rules should be 24 | configured to allow both ingress and egress from all networks for this port. 25 | 26 | Required Validator ports: 27 | 28 | * UDP/5500: ingress and egress 29 | * TCP/8800: ingress and egress 30 | 31 | These values are configurable by editing 32 | ``/etc/sawtooth-validator/txnvalidator.js`` on Linux or 33 | ``C:\Program Files(x86)\Intel\sawtooth-validator\conf\txnvalidator.js`` on 34 | Windows. 35 | 36 | 37 | Clients 38 | ======= 39 | 40 | The Sawtooth Lake client communicates with validators via TCP port 8800. 41 | Firewall rules should be adjusted to allow egress traffic on port 8800 42 | from each machine running the Sawtooth Lake client software to each validator 43 | you will be working with. If you've altered the "HttpPort" value of your 44 | validator's configuration file, this port will need to be allowed instead 45 | of the default 8800. 46 | 47 | Required Client ports: 48 | 49 | * TCP/8800: egress 50 | -------------------------------------------------------------------------------- /source/sysadmin_guide/packaging_sles.rst: -------------------------------------------------------------------------------- 1 | 2 | ************************** 3 | Creating Packages for SLES 4 | ************************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To create packages for SLES, you need the following: 10 | 11 | * SLES 12 64-bit with Internet access 12 | * git Repositories 13 | 14 | * sawtooth-core 15 | * sawtooth-validator 16 | * sawtooth-mktplace 17 | 18 | The remainder of these instructions assume a vanilla SLES 12 installation 19 | as a starting point. 20 | 21 | Install Dependencies 22 | ==================== 23 | 24 | Install the prerequisite packages: 25 | 26 | .. code-block:: console 27 | 28 | root@sles # zypper install -y \ 29 | python-setuptools \ 30 | rpmbuild \ 31 | swig \ 32 | gcc-c++ \ 33 | python-devel \ 34 | libjson-c-devel 35 | 36 | To get cryptopp, you must add an additional repository: 37 | 38 | .. code-block:: console 39 | 40 | root@sles # zypper addrepo \ 41 | http://download.opensuse.org/repositories/devel:libraries:c_c++/SLE_12/devel:libraries:c_c++.repo 42 | root@sles # zypper refresh 43 | 44 | Then, install libcryptopp-devel: 45 | 46 | .. code-block:: console 47 | 48 | root@sles # zypper install -y libcryptopp-devel 49 | 50 | Create Directory for Resulting Packages 51 | ======================================= 52 | 53 | Create a directory to hold the packages as we build them. For this guide, we 54 | will use $HOME/packages. 55 | 56 | .. code-block:: console 57 | 58 | root@sles # mkdir $HOME/packages 59 | 60 | Create Python Dependency Packages 61 | ================================= 62 | 63 | cbor 64 | ---- 65 | 66 | Create the python-cbor RPM package: 67 | 68 | .. code-block:: console 69 | 70 | root@sles # mkdir -p $HOME/projects 71 | root@sles # cd $HOME/projects 72 | root@sles # wget https://pypi.python.org/packages/source/c/cbor/cbor-0.1.24.tar.gz 73 | root@sles # tar xvfz cbor-0.1.24.tar.gz 74 | root@sles # cd cbor-0.1.24 75 | root@sles # python setup.py bdist_rpm 76 | root@sles # cp dist/cbor-*.x86_64.rpm $HOME/packages/ 77 | 78 | pybitcointools 79 | -------------- 80 | 81 | Create the python-pybitcointools RPM package: 82 | 83 | .. code-block:: console 84 | 85 | root@sles # mkdir -p $HOME/projects 86 | root@sles # cd $HOME/projects 87 | root@sles # wget https://pypi.python.org/packages/source/p/pybitcointools/pybitcointools-1.1.15.tar.gz 88 | root@sles # tar xvfz pybitcointools-1.1.15.tar.gz 89 | root@sles # cd pybitcointools-1.1.15 90 | root@sles # python setup.py bdist_rpm 91 | root@sles # cp dist/pybitcointools-*.noarch.rpm $HOME/packages/ 92 | 93 | Create SawtoothLake Python Packages 94 | =================================== 95 | 96 | Clone Repositories 97 | ------------------ 98 | 99 | Clone or copy the repositories into the SLES environment: 100 | 101 | .. code-block:: console 102 | 103 | root@sles # mkdir -p $HOME/projects 104 | root@sles # cd $HOME/projects 105 | root@sles # git clone git@github.com:IntelLedger/sawtooth-validator.git 106 | root@sles # git clone git@github.com:IntelLedger/sawtooth-core.git 107 | root@sles # git clone git@github.com:IntelLedger/sawtooth-mktplace.git 108 | 109 | .. note:: 110 | 111 | You will have to setup your SSH private key to directly clone the repository 112 | directly into the VM. 113 | 114 | At this time, if you are using a branch other than master for any of the 115 | repositories, check out the appropriate branch. 116 | 117 | Create Packages 118 | --------------- 119 | 120 | Create package from sawtooth repository: 121 | 122 | .. code-block:: console 123 | 124 | root@sles # cd $HOME/projects/sawtooth-core 125 | root@sles # python setup.py bdist_rpm 126 | root@sles # cp dist/sawtooth-core*x86_64.rpm $HOME/packages 127 | 128 | Create package from mktplace repository: 129 | 130 | .. code-block:: console 131 | 132 | root@sles # cd $HOME/projects/sawtooth-mktplace 133 | root@sles # python setup.py bdist_rpm 134 | root@sles # cp dist/sawtooth-mktplace*noarch.rpm $HOME/packages 135 | 136 | Create package from sawtooth-validator repository: 137 | 138 | .. code-block:: console 139 | 140 | root@sles # cd $HOME/projects/sawtooth-validator 141 | root@sles # python setup.py bdist_rpm 142 | root@sles # cp dist/sawtooth-validator*noarch.rpm $HOME/packages 143 | 144 | Create tar File of Packages 145 | =========================== 146 | 147 | To make it trivial to deliver the SLES RPM files, create a tar file: 148 | 149 | .. code-block:: console 150 | 151 | root@sles # cd $HOME 152 | root@sles # mv packages sawtoothlake-x.y.z-sles-packages 153 | root@sles # tar cvfj sawtoothlake-x.y.z-sles-packages.tar.bz2 sawtoothlake-x.y.z-sles-packages 154 | 155 | .. note:: 156 | 157 | The x.y.z in the above tar file name should be replaced with the version of 158 | the overall sawtoothlake deliverable. 159 | 160 | -------------------------------------------------------------------------------- /source/sysadmin_guide/packaging_ubuntu.rst: -------------------------------------------------------------------------------- 1 | 2 | **************************** 3 | Creating Packages for Ubuntu 4 | **************************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To create packages for Ubuntu, you need the following: 10 | 11 | * Ubuntu 14.04 LTS with Internet access 12 | * git Repositories 13 | 14 | * sawtooth-core 15 | * sawtooth-validator 16 | * sawtooth-mktplace 17 | 18 | The remainder of these instructions assume a vanilla Ubuntu 14.04 installation 19 | as a starting point. An easy method to obtain such a machine is by creating 20 | one with vagrant: 21 | 22 | .. code-block:: console 23 | 24 | % vagrant init ubuntu/trusty64 25 | % vagrant up 26 | % vagrant ssh 27 | 28 | Install Dependencies 29 | ==================== 30 | 31 | Apply the latest Ubuntu updates: 32 | 33 | .. code-block:: console 34 | 35 | root@ubuntu # apt-get update -y 36 | 37 | Install the prerequisite packages: 38 | 39 | .. code-block:: console 40 | 41 | root@ubuntu # apt-get install -y -q \ 42 | python-twisted \ 43 | python-twisted-web \ 44 | python-dev \ 45 | python-setuptools \ 46 | g++ \ 47 | swig \ 48 | libjson0 \ 49 | libjson0-dev \ 50 | libcrypto++-dev \ 51 | git \ 52 | python-all-dev \ 53 | python-stdeb 54 | 55 | Create Directory for Resulting Packages 56 | ======================================= 57 | 58 | Create a directory to hold the packages as we build them. For this guide, we 59 | will use $HOME/packages. 60 | 61 | .. code-block:: console 62 | 63 | vagrant@ubuntu $ mkdir $HOME/packages 64 | 65 | Create Python Dependency Packages 66 | ================================= 67 | 68 | cbor 69 | ---- 70 | 71 | Create the python-cbor deb package: 72 | 73 | .. code-block:: console 74 | 75 | vagrant@ubuntu $ cd $HOME/projects 76 | vagrant@ubuntu $ wget https://pypi.python.org/packages/source/c/cbor/cbor-0.1.24.tar.gz 77 | vagrant@ubuntu $ tar xvfz cbor-0.1.24.tar.gz 78 | vagrant@ubuntu $ cd cbor-0.1.24 79 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 80 | vagrant@ubuntu $ cp deb_dist/python-cbor*.deb $HOME/packages/ 81 | 82 | colorlog 83 | -------- 84 | 85 | Create the python-colorlog deb package: 86 | 87 | .. code-block:: console 88 | 89 | vagrant@ubuntu $ cd $HOME/projects 90 | vagrant@ubuntu $ wget https://pypi.python.org/packages/source/c/colorlog/colorlog-2.6.0.tar.gz 91 | vagrant@ubuntu $ tar xvfz colorlog-2.6.0.tar.gz 92 | vagrant@ubuntu $ cd colorlog-2.6.0 93 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 94 | vagrant@ubuntu $ cp deb_dist/python-colorlog*.deb $HOME/packages/ 95 | 96 | pybitcointools 97 | -------------- 98 | 99 | Create the python-pybitcointools deb package: 100 | 101 | .. code-block:: console 102 | 103 | vagrant@ubuntu $ cd $HOME/projects 104 | vagrant@ubuntu $ wget https://pypi.python.org/packages/source/p/pybitcointools/pybitcointools-1.1.15.tar.gz 105 | vagrant@ubuntu $ tar xvfz pybitcointools-1.1.15.tar.gz 106 | vagrant@ubuntu $ cd pybitcointools-1.1.15 107 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 108 | vagrant@ubuntu $ cp deb_dist/python-pybitcointools*.deb $HOME/packages/ 109 | 110 | Create SawtoothLake Python Packages 111 | =================================== 112 | 113 | Clone Repositories 114 | ------------------ 115 | 116 | Clone or copy the repositories into the VM environment: 117 | 118 | .. code-block:: console 119 | 120 | vagrant@ubuntu $ mkdir -p $HOME/projects 121 | vagrant@ubuntu $ cd $HOME/projects 122 | vagrant@ubuntu $ git clone git@github.com:IntelLedger/sawtooth-validator.git 123 | vagrant@ubuntu $ git clone git@github.com:IntelLedger/sawtooth-core.git 124 | vagrant@ubuntu $ git clone git@github.com:IntelLedger/sawtooth-mktplace.git 125 | 126 | .. note:: 127 | 128 | You will have to setup your SSH private key to directly clone the repository 129 | directly into the VM. 130 | 131 | At this time, if you are using a branch other than master for any of the 132 | repositories, check out the appropriate branch. 133 | 134 | Create Packages 135 | --------------- 136 | 137 | Create package from sawtooth repository: 138 | 139 | .. code-block:: console 140 | 141 | vagrant@ubuntu $ cd $HOME/projects/sawtooth-core 142 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 143 | vagrant@ubuntu $ cp deb_dist/python-sawtooth-core*.deb $HOME/packages/ 144 | 145 | Create package from mktplace repository: 146 | 147 | .. code-block:: console 148 | 149 | vagrant@ubuntu $ cd $HOME/projects/sawtooth-mktplace 150 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 151 | vagrant@ubuntu $ cp deb_dist/python-sawtooth-mktplace*.deb $HOME/packages/ 152 | 153 | Create package from sawtooth-validator repository: 154 | 155 | .. code-block:: console 156 | 157 | vagrant@ubuntu $ cd $HOME/projects/sawtooth-validator 158 | vagrant@ubuntu $ python setup.py --command-packages=stdeb.command bdist_deb 159 | vagrant@ubuntu $ cp deb_dist/python-sawtooth-validator*.deb $HOME/packages/ 160 | 161 | Create tar File of Packages 162 | =========================== 163 | 164 | To make it trivial to deliver the Ubuntu deb files, create a tar file: 165 | 166 | .. code-block:: console 167 | 168 | vagrant@ubuntu $ cd $HOME 169 | vagrant@ubuntu $ mv packages sawtoothlake-x.y.z-ubuntu-packages 170 | vagrant@ubuntu $ tar cvfj sawtoothlake-x.y.z-ubuntu-packages.tar.bz2 sawtoothlake-x.y.z-ubuntu-packages 171 | 172 | .. note:: 173 | 174 | The x.y.z in the above tar file name should be replaced with the version of 175 | the overall sawtoothlake deliverable. 176 | 177 | 178 | -------------------------------------------------------------------------------- /source/sysadmin_guide/packaging_windows.rst: -------------------------------------------------------------------------------- 1 | 2 | ***************************** 3 | Creating Packages for Windows 4 | ***************************** 5 | 6 | Prerequisites 7 | ============= 8 | 9 | To create packages for Windows, you need the following: 10 | 11 | * Windows Server 2012R2 or Windows 8.1 12 | * .Net Framework 3.5 13 | * Visual Studio 2008 14 | * Microsoft Visual C++ Compiler for Python 2.7 (VCForPython27.msi) 15 | * Python 2.7.11 Windows x86-64 MSI Installer (python-2.7.11.amd64.msi) 16 | * SWIG 3.0.7 (swigwin-3.0.7.zip) 17 | * NSIS 2.50 (nsis-2.50-setup.exe) 18 | * Crypto++ 5.6.1 (cryptopp561.zip) 19 | * json-c 0.11 (json-c-0.11.tar.gz) 20 | 21 | Download Visual C++ Compiler for Python 2.7 (VCForPython27.msi) from: 22 | 23 | http://www.microsoft.com/en-us/download/details.aspx?id=44266 24 | 25 | Download Python Windows x86-64 MSI Installer (python-2.7.11.amd64.msi) from: 26 | 27 | https://www.python.org/downloads/windows/ 28 | 29 | Download the Swig 3.0.7 (swigwin-3.0.7.zip) pre-built package from: 30 | 31 | http://www.swig.org/download.html 32 | 33 | Download the NSIS installer (nsis-2.50-setup.exe) from: 34 | 35 | http://nsis.sourceforge.net/Download 36 | 37 | Download cryptopp561.zip from: 38 | 39 | https://www.cryptopp.com/#download 40 | 41 | Download json-c-011.tar.gz from: 42 | 43 | https://s3.amazonaws.com/json-c_releases/releases/index.html 44 | 45 | The remainder of these instructions assume a vanilla Windows 2012R2 46 | machine as a starting point. 47 | 48 | Install Tools 49 | ============= 50 | 51 | Install .Net Framework 3.5 52 | -------------------------- 53 | 54 | On Windows Server 2012R2: 55 | 56 | * Open Server Manager> Add Roles and Features> 57 | * Click Next until you get to Features 58 | * Check .Net Framework 3.5 Features 59 | 60 | .. image:: ../images/net_framework.png 61 | 62 | * Click Install 63 | 64 | Install Visual Studio 2008 65 | -------------------------- 66 | 67 | If you don't have a copy, a trial version is available at: 68 | 69 | http://download.microsoft.com/download/8/1/d/81d3f35e-fa03-485b-953b-ff952e402520/VS2008ProEdition90dayTrialENUX1435622.iso 70 | 71 | * Click Install Visual Studio 2008> 72 | Accept license terms and click Next> 73 | Select Custom and click Next> 74 | 75 | .. image:: ../images/visual_studio_custom.png 76 | 77 | * Expand "Visual C++" check X64 C++ Compilers and Tools 78 | 79 | .. image:: ../images/visual_studio_x64_compiler.png 80 | 81 | * Click Install. The installation process may take around ten minutes to 82 | complete 83 | 84 | * Launch Visual Studio. Select Visual C++ Development Settings 85 | 86 | Install Microsoft Visual C++ Compiler for Python 2.7 87 | ---------------------------------------------------- 88 | 89 | Install Microsoft Visual C++ Compiler for Python 2.7 using the 90 | VCForPython27.msi package: 91 | 92 | .. code-block:: console 93 | 94 | PS C:\Users\username> cd .\Download 95 | PS C:\Users\username\Downloads> msiexec /i VCForPython27.msi ALLUSERS=1 96 | 97 | .. note:: 98 | 99 | If you don't have administrator rights, the above command should be 100 | executed without ALLUSERS=1. 101 | 102 | Install Python 103 | -------------- 104 | 105 | Use the Python 2.7.11 Windows x86-64 MSI Installer (python-2.7.11.amd64.msi) 106 | to install Python. You may be asked to reboot. 107 | 108 | Install SWIG 109 | ------------ 110 | 111 | Unzip the contents of swigwin-3.0.7.zip to ``c:\swig``. 112 | 113 | Install NSIS 114 | ------------ 115 | 116 | Use the NSIS 2.50 Installer to install NSIS to the default location. 117 | 118 | 119 | Compile and Install Source Dependencies 120 | ======================================= 121 | 122 | Crypto++ 123 | -------- 124 | 125 | Extract cryptopp561.zip 126 | ^^^^^^^^^^^^^^^^^^^^^^^ 127 | 128 | Extract cryptopp561.zip to two locations: 129 | 130 | * ``C:\build\cryptop561`` 131 | * ``C:\Program Files (x86)\Common Files\Microsoft\Visual C++ for Python\9.0\VC\include\cryptopp`` 132 | 133 | .. note:: 134 | 135 | If you installed VCForPython27.msi without administrator rights, the 136 | destination path is 137 | ``C:\Users\username\AppData\Local\Programs\Common\Microsoft\Visual C++ for Python\9.0\VC\include\cryptopp`` 138 | 139 | Source Code Modifications 140 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 141 | 142 | We need to add the CRYPTOPP_DLL macro to the class definitions in base32.h 143 | in order to export some additional non-FIPS functions. This patch should be 144 | applied to the files in ``c:\build\cryptop561``: 145 | 146 | .. code-block:: diff 147 | 148 | --- base32.h.old 2015-12-22 19:51:01.000000000 -0600 149 | +++ base32.h 2015-12-21 17:45:06.000000000 -0600 150 | @@ -7,7 +7,7 @@ 151 | 152 | //! Converts given data to base 32, the default code is based on draft-ietf-idn-dude-02.txt 153 | /*! To specify alternative code, call Initialize() with EncodingLookupArray parameter. */ 154 | -class Base32Encoder : public SimpleProxyFilter 155 | +class CRYPTOPP_DLL Base32Encoder : public SimpleProxyFilter 156 | { 157 | public: 158 | Base32Encoder(BufferedTransformation *attachment = NULL, bool uppercase = true, int outputGroupSize = 0, const std::string &separator = ":", const std::string &terminator = "") 159 | @@ -21,7 +21,7 @@ 160 | 161 | //! Decode base 32 data back to bytes, the default code is based on draft-ietf-idn-dude-02.txt 162 | /*! To specify alternative code, call Initialize() with DecodingLookupArray parameter. */ 163 | -class Base32Decoder : public BaseN_Decoder 164 | +class CRYPTOPP_DLL Base32Decoder : public BaseN_Decoder 165 | { 166 | public: 167 | Base32Decoder(BufferedTransformation *attachment = NULL) 168 | 169 | Build 170 | ^^^^^ 171 | 172 | Import the Crypto++ project into Visual Studio: 173 | 174 | * Open VS 2008 175 | * File> Open Solution> Navigate to ``c:\build\cryptopp561`` and select 176 | cryptest.sln 177 | * A box will pop up asking you to convert the solution. You can click 178 | "Finish" and then "Close" 179 | 180 | We'll need to first build the 32-bit configuration in order for the 64-bit 181 | libraries to work correctly: 182 | 183 | * Change the Solution Configuration dropdown from "Debug" to "Release" 184 | * Select Build> Build Solution from the menu. You can also initate a build by 185 | pressing the F7 key. 186 | 187 | After the build completes, build the 64-bit libraries. 188 | 189 | * Change the Solution Configuration dropdown from "Release" to 190 | "Dll-Import Release" 191 | * Change Platform to x64 192 | * Build the solution 193 | * This sometimes needs to be run twice in order to produce usable libraries 194 | 195 | The build artifacts are placed in 196 | ``c:\build\cryptopp561\x64\DLL_Output\Release`` 197 | 198 | 199 | JSON-C 200 | ------ 201 | 202 | Extract json-c-011.tar.gz 203 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 204 | 205 | Extract json-c-011.tar.gz to two locations: 206 | 207 | * ``C:\build\json-c-0.11`` 208 | * ``C:\Program Files (x86)\Common Files\Microsoft\Visual C++ for Python\9.0\VC\include\json-c`` 209 | 210 | .. note:: 211 | 212 | If you installed VCForPython27.msi without administrator rights, the 213 | destination path is 214 | ``C:\Users\username\AppData\Local\Programs\Common\Microsoft\Visual C++ for Python\9.0\VC\include\json-c`` 215 | 216 | Source Code Modifications 217 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 218 | 219 | A few changes need to be made so JSON-C will properly build on windows. 220 | These patches should be applied to the files in ``c:\build\json-c-0.11`` 221 | 222 | Changes to c:\\build\\json-c-0.11\\json_util.c: 223 | 224 | .. code-block:: diff 225 | 226 | --- json_util.c.old 2013-03-31 21:01:09.000000000 -0500 227 | +++ json_util.c 2015-12-22 11:07:56.000000000 -0600 228 | @@ -40,6 +40,7 @@ 229 | # define WIN32_LEAN_AND_MEAN 230 | # include 231 | # include 232 | +# define snprintf _snprintf 233 | #endif /* defined(WIN32) */ 234 | 235 | #if !defined(HAVE_OPEN) && defined(WIN32) 236 | @@ -158,15 +159,19 @@ 237 | */ 238 | static void sscanf_is_broken_test() 239 | { 240 | + int ret_errno; 241 | int64_t num64; 242 | + int is_int64_min; 243 | + int ret_errno2; 244 | + int is_int64_max; 245 | 246 | (void)sscanf(" -01234567890123456789012345", "%" SCNd64, &num64); 247 | - int ret_errno = errno; 248 | - int is_int64_min = (num64 == INT64_MIN); 249 | + ret_errno = errno; 250 | + is_int64_min = (num64 == INT64_MIN); 251 | 252 | (void)sscanf(" 01234567890123456789012345", "%" SCNd64, &num64); 253 | - int ret_errno2 = errno; 254 | - int is_int64_max = (num64 == INT64_MAX); 255 | + ret_errno2 = errno; 256 | + is_int64_max = (num64 == INT64_MAX); 257 | 258 | if (ret_errno != ERANGE || !is_int64_min || 259 | ret_errno2 != ERANGE || !is_int64_max) 260 | 261 | Changes to c:\\build\\json-c-0.11\\json_object.c: 262 | 263 | .. code-block:: diff 264 | 265 | --- json_object.c.old 2015-12-22 20:17:02.000000000 -0600 266 | +++ json_object.c 2015-12-22 20:16:48.000000000 -0600 267 | @@ -37,6 +37,10 @@ 268 | char* strndup(const char* str, size_t n); 269 | #endif /* !HAVE_STRNDUP */ 270 | 271 | +#ifdef WIN32 272 | +# define snprintf _snprintf 273 | +#endif /* defined(WIN32) */ 274 | + 275 | // Don't define this. It's not thread-safe. 276 | /* #define REFCOUNT_DEBUG 1 */ 277 | 278 | 279 | Build 280 | ^^^^^ 281 | 282 | * Copy ``c:\build\json-c-0.11\config.h.win32`` to 283 | ``c:\build\json-c-0.11\config.h`` 284 | 285 | * Open VS 2008 286 | * File> Open Solution> Navigate to ``c:\build\json-c-0.11`` and select 287 | json-c.sln 288 | * A box will pop up asking you to convert the solution. You can click 289 | "Finish" and then "Close" 290 | 291 | * Build> Configuration Manager> 292 | * Click the "Active solution plaform" drop-down and select "New" 293 | * Select "x64" from the "Type or select the new platform" dropdown 294 | 295 | .. image:: ../images/new_platform_solution.png 296 | 297 | * Click OK, then Close 298 | 299 | * Change the Solution Configuration dropdown from "Debug" to "Release" 300 | * Change Platform to x64 301 | * Build the solution 302 | 303 | Build artifacts are placed in ``c:\build\json-c-0.11\x64\Release`` 304 | 305 | Build Sawtooth Lake Package 306 | =========================== 307 | 308 | * Open Windows Powershell and set some environment variables 309 | 310 | .. code:: console 311 | 312 | PS C:\Users\username> $env:path += ”;c:\swig;c:\python27;C:\Program Files (x86)\NSIS” 313 | PS C:\Users\username> $env:PYTHONPATH += ";C:\Program Files (x86)\Intel\sawtooth-validator\lib\python\" 314 | 315 | * Copy cryptlib.lib and cryptopp.lib to ``c:\Python27\libs\`` 316 | 317 | .. code:: console 318 | 319 | PS C:\users\username> cp C:\build\cryptopp561\x64\DLL_Output\Release\cryptlib.lib C:\Python27\Libs 320 | PS C:\users\username> cp C:\build\cryptopp561\x64\DLL_Output\Release\cryptopp.lib C:\Python27\Libs 321 | 322 | * Copy json.lib to ``c:\Python27\libs\`` as json-c.lib 323 | 324 | .. code:: console 325 | 326 | PS C:\users\username> cp C:\build\json-c-0.11\x64\Release\json.lib C:\Python27\Libs\json-c.lib 327 | 328 | * Create the destination directory 329 | 330 | .. code:: console 331 | 332 | PS C:\users\username> mkdir "C:\Program Files (x86)\Intel\sawtooth-validator\lib\python" 333 | 334 | * Clone the git sawtooth, sawtooth-validator and marketplace git repositories into 335 | ``c:\build`` 336 | 337 | * Navigate to the directories and create the build artifacts 338 | 339 | .. code:: console 340 | 341 | PS C:\build> cd sawtooth-core 342 | PS C:\build\sawtooth-core> python setup.py install --home='C:\Program Files (x86)\Intel\sawtooth-validator' 343 | PS C:\build\sawtooth-core> cd ..\sawtooth-mktplace 344 | PS C:\build\sawtooth-mktplace> python setup.py install --home='C:\Program Files (x86)\Intel\sawtooth-validator' 345 | PS C:\build\sawtooth-mktplace> cd ..\sawtooth-validator 346 | PS C:\build\sawtooth-validator> python setup.py install --home='C:\Program Files (x86)\Intel\sawtooth-validator' 347 | 348 | * Copy cryptopp.dll into the Ledger libs directory 349 | 350 | .. code:: console 351 | 352 | PS C:\build> cp C:\build\cryptopp561\x64\DLL_Output\Release\cryptopp.dll "C:\Program Files (x86)\Intel\sawtooth-validator\lib\python\sawtooth-core--py2.7.egg\" 353 | 354 | * Copy the packaging script from the sawtooth-validator repository to ``C:\Program Files (x86)\Intel\`` 355 | 356 | .. code:: console 357 | 358 | PS C:\build> cp c:\build\sawtooth-validator\windows\sawtooth-validator.nsi "C:\Program Files (x86)\Intel\" 359 | 360 | * Run NSIS to create the installer package 361 | 362 | .. code:: console 363 | 364 | PS C:\build> makensis 'C:\Program Files (x86)\Intel\sawtooth-validator.nsi' 365 | 366 | * sawtooth-validator.exe will be created in ``C:\Program Files (x86)\Intel`` 367 | -------------------------------------------------------------------------------- /source/tutorial.rst: -------------------------------------------------------------------------------- 1 | 2 | .. _tutorial: 3 | 4 | ******** 5 | Tutorial 6 | ******** 7 | 8 | Overview 9 | ======== 10 | 11 | This tutorial walks through the process of setting up a virtual development 12 | environment for the Distributed Ledger using Vagrant and VirtualBox. At the 13 | end, you will have a running validator network and be able to use client 14 | commands to interact with it. 15 | 16 | Commands in this tutorial can be run via Terminal.app on MacOS, Git Bash on 17 | Windows, etc. 18 | 19 | Prerequisites 20 | ============= 21 | 22 | The following tools are required: 23 | 24 | * `Vagrant `_ (1.7.4 or later) 25 | * `VirtualBox `_ (5.0.10 r104061 26 | or later) 27 | 28 | On Windows, you will also need to install: 29 | 30 | * `Git for Windows `_ 31 | 32 | Git for Windows will provide not only git to clone the repositories, but also 33 | ssh which is required by Vagrant. During installation, accept all defaults. 34 | 35 | Clone Repositories 36 | ================== 37 | 38 | All five repositories (sawtooth-core, sawtooth-dev-tools, sawtooth-docs, 39 | sawtooth-mktplace, and sawtooth-validator) must be cloned into the same parent 40 | directory as follows: 41 | 42 | .. code-block:: console 43 | 44 | project/ 45 | sawtooth-core/ 46 | sawtooth-dev-tools/ 47 | sawtooth-docs/ 48 | sawtooth-mktplace/ 49 | sawtooth-validator/ 50 | 51 | This can be done by opening up a terminal and running the following: 52 | 53 | .. code-block:: console 54 | 55 | % cd $HOME 56 | % mkdir project 57 | % cd project 58 | % git clone https://github.com/IntelLedger/sawtooth-core.git 59 | % git clone https://github.com/IntelLedger/sawtooth-dev-tools.git 60 | % git clone https://github.com/IntelLedger/sawtooth-docs.git 61 | % git clone https://github.com/IntelLedger/sawtooth-mktplace.git 62 | % git clone https://github.com/IntelLedger/sawtooth-validator.git 63 | 64 | .. note:: 65 | 66 | When Vagrant is started (covered in the next section), the configuration 67 | will check for the presence of these repositories. If any of the 68 | repositories are missing, Vagrant will print an error to stderr and exit: 69 | 70 | .. code-block:: console 71 | 72 | % vagrant up 73 | ... 74 | Repository ../sawtooth-core needs to exist 75 | 76 | Environment Startup 77 | =================== 78 | 79 | In order to start the vagrant VM, change the current working directory to 80 | sawtooth-dev-tools on the host and run: 81 | 82 | .. code-block:: console 83 | 84 | % cd sawtooth-dev-tools 85 | % vagrant up 86 | 87 | .. note:: 88 | 89 | We have encountered an intermittent problem on Windows hosts which 90 | presents as an 'Operation not permitted' error in the vagrant startup 91 | output. If you encounter this error, perform a 'vagrant destroy' and 92 | then run 'vagrant up' again. 93 | 94 | Downloading the Vagrant box file, booting the VM, and running through 95 | the bootstrap scripts will take several minutes. 96 | 97 | Once the 'vagrant up' command has finished executing, run: 98 | 99 | .. code-block:: console 100 | 101 | % vagrant ssh 102 | 103 | By default, Vagrant sets up ssh keys so that users can log into the VM 104 | without setting up additional accounts or credentials. The logged in user, 105 | vagrant (uid 1000), also has permissions to execute sudo with no password 106 | required. Any number of `vagrant ssh` sessions can be established from the 107 | host. 108 | 109 | Resetting the Environment 110 | ========================= 111 | 112 | If the VM needs to be reset for any reason, it can be returned to the default 113 | state by running the following commands from the sawtooth-dev-tools directory 114 | on the host: 115 | 116 | .. code-block:: console 117 | 118 | % vagrant destroy 119 | % vagrant up 120 | 121 | .. caution:: 122 | 123 | vagrant destroy will delete all contents within the VM. However, 124 | /vagrant and /project are shared with the host and will be preserved. 125 | 126 | Building sawtooth-core 127 | ====================== 128 | 129 | The vagrant environment is setup in such a way that installation of the 130 | software is not required. However, the C++/swig code must be built. To 131 | build, run the following inside vagrant: 132 | 133 | .. code-block:: console 134 | 135 | $ cd /project/sawtooth-core 136 | $ python setup.py build 137 | 138 | Running txnvalidator 139 | ==================== 140 | 141 | To start txnvalidator, log in to the development environment with 'vagrant ssh' 142 | and run the following command: 143 | 144 | .. code-block:: console 145 | 146 | $ cd /project/sawtooth-validator 147 | $ ./bin/txnvalidator -v --config /project/sawtooth-docs/source/tutorial/txnvalidator.js 148 | 149 | This will startup txnvalidator and logging output will be printed to the 150 | terminal window. 151 | 152 | To stop the validator, press CTRL-c. 153 | 154 | .. caution:: 155 | 156 | When run as above, txnvalidator will start a new blockchain each time 157 | it starts. If you want to start txnvalidator with the previous 158 | blockchain, use the '--restore' flag. 159 | 160 | .. _mktplace-transaction-family-tutorial-label: 161 | 162 | Working with the MarketPlace Transaction Family 163 | =============================================== 164 | 165 | In this section of the tutorial, we will walk though the process of starting 166 | a single validator node and working with mktclient to create users, accounts, 167 | and perform an exchange. 168 | 169 | We will setup a couple participants, Alice and Bob, who will exchange goods 170 | (in this case, cookies) for currency (US Dollars). 171 | 172 | Configure txnvalidator.js and Start txnvalidator 173 | ------------------------------------------------ 174 | 175 | By default, the validator is not configured to support the MarketPlace 176 | transaction family or operate efficiently as a single node network. 177 | The default validator config is in: sawtooth-validator/etc/. 178 | 179 | Let's instead work with a config file specific to this tutorial. 180 | Most of the the edits are done already, but let's add the marketplace 181 | transaction family. 182 | 183 | Edit /project/sawtooth-docs/source/tutorial/txnvalidator.js 184 | and add "mktplace.transactions.market_place" to the list of transaction 185 | families: 186 | 187 | .. note:: 188 | Don't miss the comma at the end of the integer_key line, before your new 189 | line for market_place! 190 | 191 | .. code-block:: none 192 | 193 | "TransactionFamilies" : [ 194 | "ledger.transaction.integer_key", 195 | "mktplace.transactions.market_place" 196 | ], 197 | 198 | To test the changes, startup txnvalidator: 199 | 200 | .. code-block:: console 201 | 202 | $ cd /project/sawtooth-validator 203 | $ ./bin/txnvalidator -v --config /project/sawtooth-docs/source/tutorial/txnvalidator.js 204 | 205 | Keep txnvalidator running while we interact with it using mktclient below. 206 | Open a new terminal in your **host** OS and type: 207 | 208 | .. code-block:: console 209 | 210 | $ cd $HOME/project/sawtooth-dev-tools 211 | $ vagrant ssh 212 | 213 | Key Generation 214 | -------------- 215 | 216 | First, we need to create key files for each participant that we are going 217 | to use: 218 | 219 | * The Marketplace 220 | * Alice 221 | * Bob 222 | 223 | Normally these participants may be on different machines talking to different 224 | validators, but for this tutorial we control all the participants, so we 225 | generate a key for each of them: 226 | 227 | .. code-block:: console 228 | 229 | $ cd /project/sawtooth-validator 230 | $ ./bin/txnkeygen --keydir keys mkt 231 | $ ./bin/txnkeygen --keydir keys alice 232 | $ ./bin/txnkeygen --keydir keys bob 233 | 234 | .. _mktplace-object-names-label: 235 | 236 | Object Names 237 | ------------ 238 | 239 | Objects within MarketPlace are referenced (named) using paths separated by a 240 | slash (/). The number of leading slashes determines whether the reference 241 | is an absolute path, a relative path, or an identifier. 242 | 243 | ============ =================== ============================================= 244 | Count Format Description 245 | ============ =================== ============================================= 246 | Single (/) / Relative to the current key in use 247 | Double (//) /// Fully qualified name 248 | Triple (///) /// The object identifier 249 | ============ =================== ============================================= 250 | 251 | In this tutorial, we will stick to the relative paths when possible and specify 252 | absolute paths when referencing objects created by another key (another user). 253 | 254 | For example, both Alice and Bob will end up with "/USD" (a relative path), and 255 | the associated absolute paths will be "//bob/USD" and "//alice/USD". 256 | 257 | Market Initialization 258 | --------------------- 259 | 260 | We will use The Marketplace participant (mkt) to setup our example market 261 | so that Alice and Bob can exchange cookies for USD (US dollars). Bob will 262 | start with a lot of freshly baked cookies and sell them to Alice. 263 | 264 | Start mktclient as The Marketplace participant: 265 | 266 | .. code-block:: console 267 | 268 | $ cd /project/sawtooth-mktplace 269 | $ ./bin/mktclient --name mkt 270 | 271 | Now execute commands as The Marketplace participant (mkt) using the 272 | mktclient shell you just opened. As you perform these commands, you will 273 | see activity in the txnvalidator output. 274 | 275 | To start, let's register the mkt participant, create mkt's account, and 276 | a holding for tokens (a special asset only covered briefly below). 277 | 278 | .. code-block:: none 279 | 280 | //UNKNOWN> participant reg --name mkt --description "The Marketplace" 281 | //mkt> account reg --name /market/account 282 | //mkt> holding reg --name /market/holding/token --count 1 --account /market/account --asset //marketplace/asset/token 283 | 284 | The special token asset is useful for bootstrapping purposes. Tokens are 285 | non-consumable, in that they are never deducted from a holding even when 286 | exchanged for another asset. The /market/holding/token as defined has 1 token, 287 | but since it will never be deducted during an exchange, it really has an 288 | infinite number of tokens in practice. We use it below to create an inital 289 | one-time offer of USD to new participants (an offer which Bob and Alice will 290 | accept later). 291 | 292 | Now let's add the currency asset type and USD asset. Note the count of USD 293 | below is a fixed amount. By default, asset types are restricted and only the 294 | creator of the asset type can create assets of that type; so here, USD can only 295 | be created by the mkt participant. The holding will initially contain 20000000 296 | USD. The sell offer allows new participants to do a one-time exchange for 1000 297 | USD, for the purposes of new participant initialization. 298 | 299 | .. code-block:: none 300 | 301 | //mkt> assettype reg --name /asset-type/currency 302 | //mkt> asset reg --name /asset/currency/USD --type /asset-type/currency 303 | //mkt> holding reg --name /market/holding/currency/USD --count 20000000 --account /market/account --asset /asset/currency/USD 304 | //mkt> selloffer reg --name /offer/provision/USD --minimum 1 --maximum 1 --modifier ExecuteOncePerParticipant --output /market/holding/currency/USD --input /market/holding/token --ratio 1 1000 305 | 306 | Now that we have USD setup, we need to add the concept of cookies, and 307 | specifically Chocolate Chip cookies, into our blockchain. To do this, let's 308 | create a cookie asset-type and a Chocolate Chip asset. If we had different 309 | type of cookies, such as Peanut Butter, we could create additional assets 310 | to represent them. The cookie asset type is unrestricted, so anyone in the 311 | market place can create cookies. (Later, Bob will bake a batch.) 312 | 313 | .. code-block:: none 314 | 315 | //mkt> assettype reg --name /asset-type/cookie --no-restricted 316 | //mkt> asset reg --name /asset/cookie/choc_chip --type /asset-type/cookie --no-restricted 317 | 318 | The commands above are sent to the validator and applied to the network 319 | asynchronously and may not yet be committed. You can use the 'waitforcommit' 320 | to have the client block until the changes have been committed: 321 | 322 | .. code-block:: none 323 | 324 | //mkt> waitforcommit 325 | 326 | .. note:: 327 | 328 | :command:`waitforcommit` can potentially take several minutes with a small 329 | number of validators. For this section of the tutorial, we are running with 330 | a single validator and have updated the configuration such that it will 331 | usually return within a reasonable amount of time. PoET (the consensus 332 | mechanism) is optimized for more realistic use cases (not a single 333 | validator). The amount of time to wait is related to several factors, 334 | including a random number mapped to an exponential distribution. So, if you 335 | get unlucky, :command:`waitforcommit` might take a while. As the number of 336 | validators increases, the average wait time becomes more stable and 337 | predictable. 338 | 339 | Market initialization is complete, so you can now exit mktclient: 340 | 341 | .. code-block:: none 342 | 343 | //mkt> exit 344 | 345 | Registering Accounts 346 | -------------------- 347 | 348 | In the previous section, we registered the mkt account. In this section, we 349 | will register, create accounts, and create initial holdings for both Bob and 350 | Alice. 351 | 352 | First, let's register Bob. Startup mktclient using the name of Bob's key file 353 | (bob): 354 | 355 | .. code-block:: console 356 | 357 | $ cd /project/sawtooth-mktplace 358 | $ ./bin/mktclient --name bob 359 | 360 | Register Bob as a participant and create his account: 361 | 362 | .. code-block:: none 363 | 364 | //UNKNOWN> participant reg --name bob 365 | //bob> account reg --name /account 366 | 367 | Now we initialize Bob's USD holding. We create the USD holding, which will 368 | be empty (Bob can't create USD), and then accept the once-per-particiant 369 | offer from the mkt participant to receive 1000 USD. 370 | 371 | .. code-block:: none 372 | 373 | //bob> holding reg --name /USD --account /account --asset //mkt/asset/currency/USD 374 | //bob> holding reg --name /holding/token --count 1 --account /account --asset //marketplace/asset/token 375 | //bob> waitforcommit 376 | //bob> exchange --src /holding/token --dst /USD --offers //mkt/offer/provision/USD --count 1 377 | 378 | Next, let's create an empty cookie jar for Chocolate Chip cookies: 379 | 380 | .. code-block:: none 381 | 382 | //bob> holding reg --name /jars/choc_chip --account /account --asset //mkt/asset/cookie/choc_chip 383 | 384 | That is it for Bob's setup, so waitforcommit and exit: 385 | 386 | .. code-block:: none 387 | 388 | //bob> waitforcommit 389 | //bob> exit 390 | 391 | Now, let's register Alice in the same way. Startup mktclient using the name of 392 | Alice's key file (alice): 393 | 394 | .. code-block:: console 395 | 396 | $ cd /project/sawtooth-mktplace 397 | $ ./bin/mktclient --name alice 398 | 399 | Alice's initalization is the same as Bob's: 400 | 401 | .. code-block:: none 402 | 403 | //UNKNOWN> participant reg --name alice 404 | //alice> account reg --name /account 405 | //alice> holding reg --name /USD --account /account --asset //mkt/asset/currency/USD 406 | //alice> holding reg --name /holding/token --count 1 --account /account --asset //marketplace/asset/token 407 | //alice> waitforcommit 408 | //alice> exchange --src /holding/token --dst /USD --offers //mkt/offer/provision/USD --count 1 409 | //alice> holding reg --name /jars/choc_chip --account /account --asset //mkt/asset/cookie/choc_chip 410 | //alice> waitforcommit 411 | //alice> exit 412 | 413 | Now we have both Alice and Bob's account and holdings initialized. 414 | 415 | Create an Exchange Offer 416 | ------------------------ 417 | 418 | Let's assume Bob has baked two dozen Chocolate Chip cookies and wants to create 419 | an exchange offer of $2 per cookie. 420 | 421 | Start mktclient with Bob's key: 422 | 423 | .. code-block:: console 424 | 425 | $ cd /project/sawtooth-mktplace 426 | $ ./bin/mktclient --name bob 427 | 428 | Let's create a new holding representing Bob's batch of cookies and initialize 429 | it with 24 cookies. Then create an exchange offer: 430 | 431 | .. code-block:: none 432 | 433 | //bob> holding reg --name /batches/choc_chip001 --account /account --asset //mkt/asset/cookie/choc_chip --count 24 434 | //bob> exchangeoffer reg --output /batches/choc_chip001 --input /USD --ratio 2 1 --name /choc_chip_sale 435 | //bob> waitforcommit 436 | 437 | Now Bob has two dozen cookies on the market for $2 each. The ratio argument 438 | says "2 USD for 1 cookie". 439 | 440 | View the Bob's current holdings: 441 | 442 | .. code-block:: none 443 | 444 | //bob> holdings --creator //bob 445 | 1000 //bob/USD 446 | 24 //bob/batches/choc_chip001 447 | 1 //bob/holding/token 448 | 0 //bob/jars/choc_chip 449 | 450 | We can also view Bob's current offers: 451 | 452 | .. code-block:: none 453 | 454 | //bob> offers --creator //bob 455 | Ratio Input Asset (What You Pay) Output Asset (What You Get) Name 456 | 0.5 //mkt/asset/currency/USD //mkt/asset/cookie/choc_chip //bob/choc_chip_sale 457 | 458 | Great! Now Bob waits for someone to accept his offer, so we can exit 459 | mktclient: 460 | 461 | .. code-block:: none 462 | 463 | //bob> exit 464 | 465 | Accept the Exchange Offer 466 | ------------------------- 467 | 468 | Alice has decided to purchase some cookies and has decided to accept Bob's 469 | exchange offer. 470 | 471 | .. code-block:: console 472 | 473 | $ cd /project/sawtooth-mktplace 474 | $ ./bin/mktclient --name alice 475 | 476 | Execute an exchange (accepting Bob's offer): 477 | 478 | .. code-block:: none 479 | 480 | //alice> exchange --src /USD --dst /jars/choc_chip --offers //bob/choc_chip_sale --count 24 481 | //alice> waitforcommit 482 | 483 | The count above is related to the --src argument, so 24 USD for a dozen 484 | cookies. Let's see what the resulting holdings look like: 485 | 486 | .. code-block:: none 487 | 488 | //alice> holdings --creator //bob 489 | 1024 //bob/USD 490 | 12 //bob/batches/choc_chip001 491 | 1 //bob/holding/token 492 | 0 //bob/jars/choc_chip 493 | //alice> holdings --creator //alice 494 | 976 //alice/USD 495 | 1 //alice/holding/token 496 | 12 //alice/jars/choc_chip 497 | 498 | Fantastic! Bob has more USD and fewer cookies. Alice has less USD and more 499 | cookies. 500 | -------------------------------------------------------------------------------- /source/tutorial/txnvalidator.js: -------------------------------------------------------------------------------- 1 | { 2 | "Listen" : [ 3 | "localhost:5500/UDP gossip", 4 | "localhost:8800/TCP http" 5 | ], 6 | ## configuration of publicly-visible endpoint information 7 | ## used if validator is behind NAT 8 | ##"Endpoint" : { 9 | ## "Host" : "localhost", 10 | ## "Port" : 5500, 11 | ## "HttpPort" : 8800 12 | ##}, 13 | "NodeName" : "base000", 14 | "LedgerURL" : ["http://localhost:8800/"], 15 | 16 | ## pick the ledger type 17 | "LedgerType" : "lottery", 18 | "GenesisLedger" : true, 19 | 20 | ## configuration of the ledger wait time certificate 21 | ## suggested settings for single node dev environment 22 | "TargetWaitTime" : 5.0, 23 | "InitialWaitTime" : 5.0, 24 | "CertificateSampleLength" : 30, 25 | 26 | ## suggested settings for a 25 node network 27 | ## "TargetWaitTime" : 30.0, 28 | ## "InitialWaitTime" : 750.0, 29 | 30 | ## configuration of the block sizes 31 | "MinTransactionsPerBlock" : 1, 32 | "MaxTransactionsPerBlock" : 1000, 33 | 34 | ## configuration of the topology 35 | ## "TopologyAlgorithm" : "BarabasiAlbert", 36 | ## "MaximumConnectivity" : 15, 37 | ## "MinimumConnectivity" : 1, 38 | 39 | "TopologyAlgorithm" : "RandomWalk", 40 | "TargetConnectivity" : 3, 41 | 42 | ## configuration of the network flow control 43 | "NetworkFlowRate" : 96000, 44 | "NetworkBurstRate" : 128000, 45 | "NetworkDelayRange" : [ 0.00, 0.10 ], 46 | "UseFixedDelay" : true, 47 | 48 | ## configuration of the transaction families to include 49 | ## in the validator 50 | "TransactionFamilies" : [ 51 | "ledger.transaction.integer_key" 52 | ], 53 | 54 | ## do not restart 55 | "Restore" : false, 56 | 57 | ## This value should be set to the identifier which is 58 | ## permitted to send shutdown messages on the network. 59 | ## By default, no AdministrationNode is set. 60 | ## "AdministrationNode" : "19ns29kWDTX8vNeHNzJbJy6S9HZiqHZyEE", 61 | 62 | ## key file 63 | "KeyFile" : "{key_dir}/{node}.wif" 64 | } 65 | --------------------------------------------------------------------------------