Merge pull request #4 from multiparty/tutorials

Tutorials directory with Intro to JIGG Tutorial

Author: wyatt-howe

.gitmodules

@@ -21,8 +21,16 @@ npm install
     │  ├─ comm/         Communications modules (such as for OT)
     │  ├─ modules/         Data structure modules (such as circuits)
     │  └─ utils/        Other utility modules (such as cryptographic primitives)
-    └─ test/            End-to-end tests
+    ├─ test/            End-to-end tests
+    └─ tutorial/        Interactive tutorial on using JIGG
 
+## Running The tutorial
+
+You can run the tutorial interactively on your local machine, after cloning JIGG, by using
+```shell
+cd path/to/JIGG
+npm run tutorial
+```
 
 ## Running Demo Circuit Applications
 
@@ -77,7 +85,7 @@ JIGG can parse a circuit in the standardized '[Bristol](https://homes.esat.kuleu
 ```
 
 ### Circuit Assembler
-To create a new circuit, write a macro with existing circuits as its gates and run the [macro-circuit-assembler](https://github.com/wyatt-howe/macro-circuit-assembler/tree/casm) with:
+To create a new circuit, write a macro with existing circuits as its gates and run the [macro-circuit-assembler](https://github.com/wyatt-howe/macro-circuit-assembler/) with:
 
 ```shell
 npm run casm -- <path_to_macro> <output_path>

README.md

@@ -1,6 +1,6 @@
-3 7
-2 2 2
-1 1
+3 7    # 3 gates, 7 wires
+2 2 2  # 2 parties, 2 bits for each of them
+1 1    # 1 output, 1 bit long
 2 1 0 1 4 AND
 2 1 2 3 5 AND
 2 1 4 5 6 AND

circuits/bristol/logic-and-4-bit.txt

@@ -0,0 +1,7 @@
+4 8    # 4 gates, 8 wires
+2 2 2  # 2 parties, 2 bits for each of them
+1 1    # 1 output, 1 bit long
+2 1 0 1 4 AND  # 2 inputs, 1 output, wire #0 AND wire #1 --> wire #4
+2 1 2 3 5 AND
+2 1 4 5 6 AND
+1 1 6 7 INV  # 1 input, 1 output, invert wire 6 --> wire 7

circuits/bristol/logic-nand-4-bit.txt

@@ -32,7 +32,7 @@
 
     <input type="text" id="nav-search" placeholder="Search" />
 
-    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h2><a href="../tutorial/intro.html" class="menu-item" >Tutorial</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
 </nav>
 
 <div id="main">
@@ -1186,7 +1186,7 @@ <h4 class="name" id="start"><span class="type-signature"></span>start<span class
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Thu Feb 13 2020 12:30:51 GMT-0500 (Eastern Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Feb 18 2020 13:36:11 GMT-0500 (EST) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

dist/jigg.js

@@ -32,7 +32,7 @@
 
     <input type="text" id="nav-search" placeholder="Search" />
 
-    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h2><a href="../tutorial/intro.html" class="menu-item" >Tutorial</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
 </nav>
 
 <div id="main">
@@ -482,7 +482,7 @@ <h5>Returns:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Thu Feb 13 2020 12:30:51 GMT-0500 (Eastern Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Feb 18 2020 13:36:11 GMT-0500 (EST) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/Agent.html

@@ -32,7 +32,7 @@
 
     <input type="text" id="nav-search" placeholder="Search" />
 
-    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h2><a href="../tutorial/intro.html" class="menu-item" >Tutorial</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
 </nav>
 
 <div id="main">
@@ -78,7 +78,13 @@ <h2>Project Layout</h2>
 │  ├─ comm/         Communications modules (such as for OT)
 │  ├─ modules/         Data structure modules (such as circuits)
 │  └─ utils/        Other utility modules (such as cryptographic primitives)
-└─ test/            End-to-end tests
+├─ test/            End-to-end tests
+└─ tutorial/        Interactive tutorial on using JIGG
+</code></pre>
+<h2>Running The tutorial</h2>
+<p>You can run the tutorial interactively on your local machine, after cloning JIGG, by using</p>
+<pre class="prettyprint source lang-shell"><code>cd path/to/JIGG
+npm run tutorial
 </code></pre>
 <h2>Running Demo Circuit Applications</h2>
 <p>Start the communications server from server.js with the command below:</p>
@@ -117,16 +123,15 @@ <h3>Circuit Format</h3>
 2 1 4 6 7 AND
 </code></pre>
 <h3>Circuit Assembler</h3>
-<p>To create a new circuit, write a macro with existing circuits as its gates and run the <a href="https://github.com/wyatt-howe/macro-circuit-assembler/tree/casm">macro-circuit-assembler</a> with:</p>
+<p>To create a new circuit, write a macro with existing circuits as its gates and run the <a href="https://github.com/wyatt-howe/macro-circuit-assembler/">macro-circuit-assembler</a> with:</p>
 <pre class="prettyprint source lang-shell"><code>npm run casm -- &lt;path_to_macro> &lt;output_path>
 </code></pre>
 <p>For example, this macro assembles an AND circuit over 8 bits using
 existing 4 bit AND circuits:</p>
 <pre class="prettyprint source"><code>npm run casm -- circuits/macros/and-8.casm circuits/and-8.txt
 </code></pre>
 <h2>Running Tests</h2>
-<h3>End-to-end Tests</h3>
-<p>All of the built-in test vectors can be verified in <code>npm test</code>. The tests will run a server automatically.</p>
+<p>All of the built-in test vectors can be verified in <code>npm test</code>. The tests will run a server automatically. These are end-to-end tests.</p>
 <h2>Capabilities</h2>
 <p>JIGG is designed for semi-honest parties (in either node or in the browser). We support point-and-permute, free-XOR, free single-input gates, and encryption from a random oracle (fixed-key XChaCha20). The half-AND optimization is compatible but not yet supported. The default label size is 128 bits and relies on JavaScript's Uint8Array class. The <a href="https://github.com/wyatt-howe/jigg/tree/simple-labels"><code>simple-labels</code></a> branch demonstrates dynamically-sized labels (that are 53 bits in length or less) without using arrays. Some potential improvements are listed in the to-do section.</p>
 <h2>Contributing</h2>
@@ -152,7 +157,7 @@ <h2>Information and Collaborators</h2>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Thu Feb 13 2020 12:30:51 GMT-0500 (Eastern Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Feb 18 2020 13:36:11 GMT-0500 (EST) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/Server.html

@@ -32,7 +32,7 @@
 
     <input type="text" id="nav-search" placeholder="Search" />
 
-    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h2><a href="../tutorial/intro.html" class="menu-item" >Tutorial</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
 </nav>
 
 <div id="main">
@@ -106,7 +106,7 @@ <h1 class="page-title">jigg.js</h1>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Thu Feb 13 2020 12:30:51 GMT-0500 (Eastern Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Feb 18 2020 13:36:11 GMT-0500 (EST) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/index.html

@@ -32,7 +32,7 @@
 
     <input type="text" id="nav-search" placeholder="Search" />
 
-    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/multiparty/jigg" target="_blank" class="menu-item" id="github_link" >Github Repo</a></h2><h2><a href="../tutorial/intro.html" class="menu-item" >Tutorial</a></h2><h3>Classes</h3><ul><li><a href="Agent.html">Agent</a><ul class='methods'><li data-type='method'><a href="Agent.html#addProgressListener">addProgressListener</a></li><li data-type='method'><a href="Agent.html#disconnect">disconnect</a></li><li data-type='method'><a href="Agent.html#getOutput">getOutput</a></li><li data-type='method'><a href="Agent.html#loadCircuit">loadCircuit</a></li><li data-type='method'><a href="Agent.html#setInput">setInput</a></li><li data-type='method'><a href="Agent.html#start">start</a></li></ul></li><li><a href="Server.html">Server</a><ul class='methods'><li data-type='method'><a href="Server.html#makeAgent">makeAgent</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-Browser.html">Browser</a></li><li><a href="module-JIGG.html">JIGG</a></li></ul>
 </nav>
 
 <div id="main">
@@ -251,7 +251,7 @@ <h1 class="page-title">jiggClient.js</h1>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Thu Feb 13 2020 12:30:51 GMT-0500 (Eastern Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Feb 18 2020 13:36:11 GMT-0500 (EST) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>