Merge pull request #1225 from o1-labs/docs/improve-examples

Some example improvements

package.json

@@ -56,7 +56,7 @@
     "prepublish:web": "NODE_ENV=production node src/build/buildWeb.js",
     "prepublish:node": "npm run build && NODE_ENV=production node src/build/buildNode.js",
     "prepublishOnly": "npm run prepublish:web && npm run prepublish:node",
-    "dump-vks": "./run src/examples/vk_regression.ts --bundle --dump ./src/examples/regression_test.json",
+    "dump-vks": "./run tests/vk-regression/vk-regression.ts --bundle --dump",
     "format": "prettier --write --ignore-unknown **/*",
     "clean": "rimraf ./dist && rimraf ./src/bindings/compiled/_node_bindings",
     "clean-all": "npm run clean && rimraf ./tests/report && rimraf ./tests/test-artifacts",

run-ci-tests.sh

@@ -42,7 +42,7 @@ case $TEST_TYPE in
 
 "Verification Key Regression Check")
   echo "Running Regression checks"
-  ./run ./src/examples/vk_regression.ts --bundle
+  ./run ./tests/vk-regression/vk-regression.ts --bundle
   ;;
 
 "CommonJS test")

src/build/buildExample.js

@@ -18,6 +18,9 @@ async function buildAndImport(srcPath, { keepFile = false }) {
 
 async function build(srcPath, isWeb = false) {
   let tsConfig = findTsConfig() ?? defaultTsConfig;
+  // TODO hack because ts.transpileModule doesn't treat module = 'nodenext' correctly
+  // but `tsc` demands it to be `nodenext`
+  tsConfig.compilerOptions.module = 'esnext';
 
   let outfile = srcPath.replace('.ts', '.tmp.js');
 
@@ -46,6 +49,9 @@ async function build(srcPath, isWeb = false) {
 
 async function buildOne(srcPath) {
   let tsConfig = findTsConfig() ?? defaultTsConfig;
+  // TODO hack because ts.transpileModule doesn't treat module = 'nodenext' correctly
+  // but `tsc` demands it to be `nodenext`
+  tsConfig.compilerOptions.module = 'esnext';
 
   let outfile = path.resolve(
     './dist/node',
@@ -74,7 +80,7 @@ const defaultTsConfig = {
     target: 'esnext',
     importHelpers: true,
     strict: true,
-    moduleResolution: 'node',
+    moduleResolution: 'nodenext',
     esModuleInterop: true,
     skipLibCheck: true,
     forceConsistentCasingInFileNames: true,

src/examples/README.md

@@ -0,0 +1,25 @@
+# o1js Examples
+
+This folder contains many examples for using o1js. Take a look around!
+
+## Running examples
+
+You can run most examples using Node.js from the root directory, using the `./run` script:
+
+```
+./run src/examples/some-example.ts
+```
+
+Some examples depend on other files in addition to `"o1js"`. For those examples, you need to add the `--bundle` option to bundle them before running:
+
+```
+./run src/examples/multi-file-example.ts --bundle
+```
+
+Most of the examples do not depend on Node.js specific APIs, and can also be run in a browser. To do so, use:
+
+```
+./run-in-browser.js src/examples/web-compatible-example.ts
+```
+
+After running the above, navigate to http://localhost:8000 and open your browser's developer console to see the example executing.

src/examples/benchmarks/hash-witness.ts

@@ -2,7 +2,7 @@
  * benchmark witness generation for an all-mul circuit
  */
 import { Field, Provable, Poseidon } from 'o1js';
-import { tic, toc } from './tic-toc.js';
+import { tic, toc } from '../utils/tic-toc.js';
 
 // parameters
 let nPermutations = 1 << 12; // 2^12 x 11 rows < 2^16 rows, should just fit in a circuit

src/examples/benchmarks/mul-web.ts

@@ -2,7 +2,7 @@
  * benchmark a circuit filled with generic gates
  */
 import { Circuit, Field, Provable, circuitMain, ZkProgram } from 'o1js';
-import { tic, toc } from './tic-toc.js';
+import { tic, toc } from '../utils/tic-toc.js';
 
 // parameters
 let nMuls = (1 << 16) + (1 << 15); // not quite 2^17 generic gates = not quite 2^16 rows

src/examples/benchmarks/mul-witness.ts

@@ -2,7 +2,7 @@
  * benchmark witness generation for an all-mul circuit
  */
 import { Field, Provable } from 'o1js';
-import { tic, toc } from './tic-toc.js';
+import { tic, toc } from '../utils/tic-toc.js';
 
 // parameters
 let nMuls = (1 << 16) + (1 << 15); // not quite 2^17 generic gates = not quite 2^16 rows

src/examples/benchmarks/mul.ts

@@ -2,7 +2,7 @@
  * benchmark a circuit filled with generic gates
  */
 import { Circuit, Field, Provable, circuitMain, ZkProgram } from 'o1js';
-import { tic, toc } from '../zkapps/tictoc.js';
+import { tic, toc } from '../utils/tic-toc.node.js';
 
 // parameters
 let nMuls = (1 << 16) + (1 << 15); // not quite 2^17 generic gates = not quite 2^16 rows

src/examples/circuit/README.md

@@ -0,0 +1,7 @@
+# `Circuit` examples
+
+These examples show how to use `Circuit`, which is a simple API to write a single circuit and create proofs for it.
+
+In contrast to `ZkProgram`, `Circuit` does not pass through Pickles, but creates a proof with Kimchi directly. Therefore, it does not support recursion, but is also much faster.
+
+Note that `Circuit` proofs are not compatible with Mina zkApps.

src/examples/ex00_preimage.ts → src/examples/circuit/preimage.ts

@@ -1,28 +1,18 @@
-import {
-  Poseidon,
-  Field,
-  Circuit,
-  circuitMain,
-  public_,
-  isReady,
-} from 'o1js';
-
-/* Exercise 0:
-
-Public input: a hash value h
-Prove:
-  I know a value x such that hash(x) = h 
-*/
-
+import { Poseidon, Field, Circuit, circuitMain, public_ } from 'o1js';
+
+/**
+ * Public input: a hash value h
+ *
+ * Prove:
+ *   I know a value x such that hash(x) = h
+ */
 class Main extends Circuit {
   @circuitMain
   static main(preimage: Field, @public_ hash: Field) {
     Poseidon.hash([preimage]).assertEquals(hash);
   }
 }
 
-await isReady;
-
 console.log('generating keypair...');
 const kp = await Main.generateKeypair();
 

src/examples/ex02_root.ts → src/examples/circuit/root.ts

@@ -1,18 +1,17 @@
-import { Field, Circuit, circuitMain, public_, UInt64, Gadgets } from 'o1js';
-
-/* Exercise 2:
-
-Public input: a field element x
-Prove:
-  I know a value y that is a cube root of x.
-*/
+import { Field, Circuit, circuitMain, public_, Gadgets } from 'o1js';
 
+/**
+ * Public input: a field element x
+ *
+ * Prove:
+ *   I know a value y < 2^64 that is a cube root of x.
+ */
 class Main extends Circuit {
   @circuitMain
-  static main(@public_ y: Field, x: UInt64) {
-    Gadgets.rangeCheck64(x.value);
+  static main(@public_ x: Field, y: Field) {
+    Gadgets.rangeCheck64(y);
     let y3 = y.square().mul(y);
-    y3.assertEquals(x.value);
+    y3.assertEquals(x);
   }
 }
 
@@ -23,15 +22,15 @@ console.timeEnd('generating keypair...');
 
 console.log('prove...');
 console.time('prove...');
-const x = UInt64.from(8);
-const y = new Field(2);
-const proof = await Main.prove([x], [y], kp);
+const x = Field(8);
+const y = Field(2);
+const proof = await Main.prove([y], [x], kp);
 console.timeEnd('prove...');
 
 console.log('verify...');
 console.time('verify...');
 let vk = kp.verificationKey();
-let ok = await Main.verify([y], vk, proof);
+let ok = await Main.verify([x], vk, proof);
 console.timeEnd('verify...');
 
 console.log('ok?', ok);

src/examples/internals/README.md

@@ -0,0 +1,5 @@
+# Examples: Internals
+
+This folder contains examples which highlight inner workings and less-documented behaviours of o1js.
+
+These examples might be useful for advanced users and contributors.