o1js Documentation

The src/examples/crypto/ directory contains implementation examples for advanced cryptographic primitives that can be used within provable o1js code. These examples demonstrate how to handle operations that fall outside the standard field arithmetic of the Mina blockchain.

Available examples include:

• Non-native field arithmetic: Using foreign-field.ts to perform arithmetic on fields other than the native Mina field.
• Non-native ECDSA verification: Using ecdsa.ts to verify Elliptic Curve Digital Signature Algorithm signatures.
• Provable big integer arithmetic: Using bigint.ts for arithmetic involving large integers.
• RSA signature verification: A low-level implementation found in the rsa/ directory, which utilizes a custom bigint type optimized with efficient o1js range checks.

Nix can consume significant disk space because nix develop creates new generations. Use these strategies to manage storage:

Storage Management

• Enable Auto-optimise: It is recommended to set auto-optimise-store = true in your Nix configuration. This replaces duplicate files with symlinks.
• Manual Optimization: Run nix-store --optimize to clean up the store retroactively.
• Garbage Collection: Run nix-store --gc to free space. To prevent the GC from removing essential dev-shell roots, consider using direnv and nix-direnv.

Runtime Optimization

When using the project's flake.nix, you can accept optimized settings (like max-jobs = auto and mina-nix-cache usage) by using the following flag:

nix develop o1js#default --accept-flake-config

In o1js, you can choose between two primary abstractions for writing circuits: ZkFunction and ZkProgram.

• ZkFunction: A simple API designed to write a single circuit and create proofs for it. It uses Kimchi directly without passing through Pickles. This makes it much faster than ZkProgram, but it does not support recursion.
• ZkProgram: A more complex abstraction that uses Pickles. It supports recursion but is slower than ZkFunction.

Important Compatibility Note: Proofs generated using ZkFunction are not compatible with Mina zkApps.

Hash functions in o1js are located under the Hash namespace. These functions operate over binary data and require binary arithmetic. To use them effectively, you may need to extend the Bytes class to specify the required length of the byte arrays being hashed.

For specific implementations, refer to the documentation for:

• Keccak
• SHA-256

o1js uses the Nix registry to manage git submodules. You can enter a development shell that provides all dependencies required for npm scripts (including npm run build:bindings-all) using one of the following methods:

• Run ./pin.sh and then nix develop o1js#default
• Use direnv with the provided .envrc file.

The project uses Nix Flakes for packaging. It is highly recommended to enable flakes for better performance and convenience. Ensure you are running Nix $\geqslant$ 2.5.

To enable flakes, create or update your nix.conf file (preferably in your user config directory) with the following line:

mkdir -p "${XDG_CONFIG_HOME-${HOME}/.config}/nix"
echo 'experimental-features = nix-command flakes' > "${XDG_CONFIG_HOME-${HOME}/.config}/nix/nix.conf"

Verify flake support is active by running:

nix flake metadata github:nixos/nixpkgs

To optimize performance or profile your zkApp, you can use the Chrome Debugger with Node.js.

Use the provided run-debug script, which starts a Node.js process with the --inspect-brk flag (pausing execution until a debugger is attached) and --enable-source-maps (allowing you to debug o1js code directly).

Steps:

1. Run the script: ./run-debug <path-to-your-zkapp> --bundle.
2. Open Chrome and navigate to chrome://inspect.
3. Attach the Chrome Debugger to the Node.js process to set breakpoints, inspect variables, and profile performance.

The project includes unit, integration, and end-to-end tests.

Unit and Integration Tests

• Standard test suite: npm run test or npm run test:unit.
• Integration tests: npm run test:integration.
• Individual Jest tests: ./jest <path/to/test.ts>.

Special Requirements

• mina-signer tests: You must build from inside the src/mina-signer directory first:

  cd src/mina-signer
  npm run build
  cd ../..
  npm run test

End-to-End (E2E) Browser Tests

E2E tests are not run by default. To run them:

npm install
npm run e2e:install
npm run build:web
npm run e2e:prepare-server
npm run test:e2e
npm run e2e:show-report

Internal contributors with an open PR can use npm run build:bindings-download on any commit where CI has run (or is currently running). If CI is in progress, the command uses gh run watch to monitor progress.

If you encounter a merge conflict where CI does not run on every new commit, use:

npm run build:bindings-remote

This triggers a self-hosted runner to build the bindings for your specific commit and downloads them once finished.

You can install the mina-signer NodeJS SDK using either yarn or npm to enable signing of strings, payments, and delegations for various Mina networks.

yarn add mina-signer
# or with npm:
npm install --save mina-signer