o1-labs / o1js

TypeScript framework for zk-SNARKs and zkApps

o1js  

ℹ️ o1js is an evolution of SnarkyJS which saw 49 updated versions over two years of development with 43,141 downloads.

This name change to o1js reflects the evolution of our vision for the premiere toolkit used by developers to build zero knowledge-enabled applications, while paying homage to our technology's recursive proof generation capabilities.

Your favorite functionality stays the same and transitioning to o1js is a quick and easy process:

• To update zkApp-cli, run the following command:

  npm i -g zkapp-cli@latest

• To remove the now-deprecated SnarkyJS package and install o1js, run the following command:

  npm remove snarkyjs && npm install o1js

• For existing zkApps, make sure to update your imports from snarkyjs to o1js

• No need to redeploy, you are good to go!

o1js

o1js helps developers build apps powered by zero knowledge (zk) cryptography.

The easiest way to write zk programs is using o1js.

o1js is a TypeScript library for zk-SNARKs and zkApps. You can use o1js to write zk smart contracts based on zero-knowledge proofs for the Mina Protocol.

o1js is automatically included when you create a project using the zkApp CLI.

Learn More

• To learn more about developing zkApps, see the zkApp Developers docs.

• For guided steps building and using zkApps, see the zkApp Developers Tutorials.

• To meet other developers building zkApps with o1js, participate in the #zkapps-developers channel on Mina Protocol Discord.

• For a list of changes between versions, see the CHANGELOG.

• To stay up to date with o1js, see the O(1) Labs Blog.

Contributing

o1js is an open source project. We appreciate all community contributions to o1js!

See the Contributing guidelines for ways you can contribute.

Development Workflow

For guidance on building o1js from source and understanding the development workflow, see o1js README-dev.

Community Packages

High-quality community packages from open source developers are available for your project.

• o1js-elgamal A partially homomorphic encryption library for o1js based on Elgamal encryption: GitHub and npm
• o1js-pack A library for o1js that allows a zkApp developer to pack extra data into a single Field. GitHub and npm

To include your package, see Creating high-quality community packages.

o1js's Issues

Support flows where fee-payer signs later

[BUG] UInt64.assertGt and UInt32.assertGt do not work correctly

https://github.com/o1-labs/snarkyjs/blob/e08f981166be59d962e9cfa196da1ae7e33f1368/src/lib/int.ts?_pjax=%23repo-content-pjax-container#L153

Hi, these two methods(UInt64.assertGt and UInt32.assertGt) do not work correctly, as shown in the code. Is the assertGte method also missing?

For every section of the SnarkyJS, link to the relevant section of the docs (if helpful)

E.g.

• https://docs.minaprotocol.com/en/snapps/how-snapps-work#deploying-a-smart-contract

Merkle tree support

`inProver` returns true in unexpected places

Circuit.inProver seems to behave weird with the current implementation.
They are false in the beginning but stay true after the first Mina.transaction was run

(Observed in simple SmartContract example, needs proper investigation)

Make arrayProp work before isReady

This just means Circuit.array has to be ported to JS

Add secp256k1 signature verification support

Getting the value of a Field using toString()

Hello,
The .toStrting() is giving the value of the Field. I think this is a bug in the Mocking and not intended, right?
You can check how I am able to get the numeric value of UInt64 here:
https://github.com/Muhammad-Altabba/snarkyjs-tender/blob/bf6ba9503fe905c65376237c18a81422c119cc28/src/sealed-bid-auction-snapp.ts#L90

Consider supporting mock snapp GraphQL API endpoint

We could consider allowing devs to send transactions to Mina's mock/dry run API endpoint, which will show them the rest of a transaction without actually executing the transaction state changes on chain.

Low priority.

Building Snarkette

I would like to know how to build the dune dependency in https://github.com/o1-labs/snarkyjs. I am trying to learn to use a dune dependency in a js project as you did here by reading your code. It seems we are missing "../../config.mlh" required by the dune file. Can this script be provided?

error output:

mando@mandalarian ~/G/s/snarkette (master)> dune build
Info: Creating file dune-project with this contents:
| (lang dune 2.8)
File "dune", line 5, characters 20-36:
5 |  (preprocessor_deps ../../config.mlh)
                        ^^^^^^^^^^^^^^^^
Error: path outside the workspace: ../../config.mlh from default

Thank you.

Also, nice work on ocamlbyexample!

Change `assertBoolean()` > `assertBool()`

For consistency given we use new Bool().

Tx construction

Remove spin lock hack

This is a longer-term issue that probably requires some ocaml code to be rewritten to expect Promises when calling into the Wasm produced by Rust (marlin_plonk_bindings).

We currently have an awful hack in JS land just to present functions as sync to the JSOO code that in reality are async, context here:

https://o1-labs.slack.com/archives/C028Q27R8UC/p1633028074087000

It would make the JS project so much nicer if we could avoid this and deal with Promises from end to end

Field constructor vs static methods

Do we want stuff like Field.fromBitstring()?

During build, warn if unsupported JS/TS language constructs are used

During SnarkyJS’ build, we could help guide developers by checking for unsupported language constructs (e.g. throw, conditionals, native ternaries) and warning developers. Likely using an abstract syntax tree to do this reliably.

Related: we want to set up matching ES Lint custom rules in the Snapp CLI's projec-ts, if possible, to warn developers as they wrote their app.

Minimal @method decorator for end-to-end testing

Add longer forms, `lte`-> `lessThanOrEqual`

and deprecate (but not remove) short forms

RFC for / discuss a solution to manage integer overflows, if needed

Change tsconfig.json `target` value to ES2020

Izaak has reported that decorators don't behave as expected on the feature/workshop-examples branch. By changing the target value from esnext to es2020, the decorator error he was experiencing was fixed. Further work should be made to figure out why this was a breaking change.

Because esnext targets the highest version of TypeScript that the project supports, maybe we should be more conservative with how we specify the target value.

Playground link of correct behavior:
https://www.typescriptlang.org/play?ts=4.4.4#code/GYVwdgxgLglg9mABMOcAUAPAXIsIC2ARgKYBOAlIgN4BQNpxUIpSoksCiaUAFjAM44AhmACeAGkRQhpAOaNhYyQGtionPyikYYWZVqJDiCAn5wANsQB05uLLQByAYgCCDydLmMrJsJtIg0HCkiAC84a7kANw0RsamFta29g68YALuUnz80bFGvmaWNnaOUJme8lC5cQDyhABWxNBWACbEwDrEAAqkcAAOZFCi3DKVKmqSVIj8ClwYlKEAfNTxfonFKTNQUGQO5AC+kpU4aAvLDiakDNAO++Q0+w80QoT+QtDG5kL8-IgAQtQ6I86BAvj9XIhiBgdmAWr8AYC4gABFDoACMAAZ7nFsNMtDpZDE8oYClpAlBgqdEXEjPwQANSKdiXFeAIrBgwogHAB3Xq6BwxOKPR6kxBCTlgYjc1ynIkFdbJNBCdn3IA

Output should specify the variable x as the value "correct" when run. On commit 953cc6020966e90e36f3410237a64a0d16dcc6c5, the same example is in index.ts and fails to set the variable correctly with the same code as the playground. To run the code on commit 953cc..., run npm run exec

Admin handling

When using `Circuit.if(...)`, Error: rangeCheckHelper: Expected 289...661 to fit in 64 bits

Hello,
When using Circuit.if(...) an exception occurs:

Error: rangeCheckHelper: Expected 28948022309329048855892746252171976963363056481941560715954676764349966633661 to fit in 64 bits
at Jv (eval at Be (:3010/js/chunk-QIK4YCST.js:7670), :3210:1356)
at eval (eval at Be (:3010/js/chunk-QIK4YCST.js:7670), :3210:8522)
at am (eval at Be (:3010/js/chunk-QIK4YCST.js:7670), :4:23673)
at Object.eval [as rangeCheckHelper] (eval at Be (:3010/js/chunk-QIK4YCST.js:7670), :4:80689)
at z.lte (:3010/js/chunk-QIK4YCST.js:8582)
at z.lt (:3010/js/chunk-QIK4YCST.js:8590)
at SealedBidAuctionSnapp.bid (:3010/js/sealed-bid-auction-snapp-HCY3URRZ.js:52)
at :3010/js/sealed-bid-auction-snapp-HCY3URRZ.js:135
at :3010/js/chunk-QIK4YCST.js:8980
at As (eval at Be (:3010/js/chunk-QIK4YCST.js:7670), :3210:24862)

To reproduce, uncomment the commented lines at https://github.com/Muhammad-Altabba/snarkyjs-tender/blob/bf6ba9503fe905c65376237c18a81422c119cc28/src/sealed-bid-auction-snapp.ts#L80 and run the project.

Is this an expected behavior? Could you please elaborate on this?

Thanks in advace,

[feature request] exposing/(de)serializing proof and verification key

Thins idea was also mentioned in Discord.

Idea: Potentially allowing to "export" and "import" proofs and their coressponding verification key to allow verification and proofing of code outside of the Mina blockchain, inside of web2.0.

Reason: It would open up SnarkyJS to more developers, allowing many web 2.0 devs and other developers to utilize the power of zero knowledge proofs to some extend in normal web applications.

Possible usage: What it could look like

// example from ex00_preimage.ts

class Main extends Circuit {
  @circuitMain
  static main(preimage: Field, @public_ hash: Field) {
    Poseidon.hash([preimage]).assertEquals(hash);
  }
}

// ... 

let proof = Main.prove(/* .. */); // returns the proof
let encodedProof = proof.toBase58()) // potentially encoded in base58 for easy use eg 'RJcTKtswS9xgY4FDfxCq4ZaLRfQwGME8GYPFGpxieWZXJMGUuqN1zdKYEM6dLZER'  

let verificationKey = Main.getVerificationKey(); // returns the verification key; potentially also encoded for easy use

// usage in a different application

class MyVerifier extends Verifier {
  constructor(key: VerificationKey) {
     // ...
  }
}

let verificationKey = 'someVerificationKeyEncoded';
let myVerifier = new Verifier(VerificationKey.fromString(verificationKey))

let proof = 'someProofEncoded';
let isValid = myVerifier.verify(Proof.fromString(proof)); // returns true if proof matches verification key

Is something like that feasible and makes sense?
Or is something like that potentially even planned already?

Thanks!

Create more useful CI tests

Get build to work on the client

Ensure tree shaking is used during the build

We need to get the client bundle size much smaller.

streamline releases

it'd be nice to leverage CI as much as possible to perform releases.

(Optional) Automatic releases and changelog, using Semantic release, Commitizen, Conventional changelog and Husky (for the git hooks)

from https://github.com/alexjoverm/typescript-library-starter

@mitschabaude points to https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages also

[feature request] Decouple signing from transaction creation

In current snarkyjs (v0.1.11) creating and sending a transaction looks like this:

await Mina.transaction(senderPrivateKey, async () => {
    // transaction code
  })
    .send()
    .wait();

This means that the frontend code that creates the transaction and waits for it also has access to the private key.
I think it would be very useful to be able to create transactions without having direct access to the key, but rather by getting access to a signer object.

A back of the napkin example would be something like this:

interface MinaSigner {
  sign: (data: Uint8Array) => Promise<Uint8Array>
}

class SimpleSigner implements MinaSigner {
  constructor(privateKey: string) {}
  async sign(data: Uint8Array): Promise<Uint8Array> {
      // ...implement the actual signing
  }
}

const senderSigner = new MinaSigner(senderPrivateKey)

await Mina.transaction(senderSigner, async () => {
    // transaction code
  })
    .send()
    .wait();

The benefit of this approach is that you can separate concerns more cleanly between key management and frontend code.
You can let a wallet or an HSM handle keys and not have to trust that the frontend has no vulnerability that allows someone to sniff keys.

Convert the build to output ES6

Todo: Check with Nathan & Martin to ask about their latest progress, before starting.

Issue: JS of OCaml only builds to CommonJS.

Naming: Replace all names of the form: "ofX" with "fromX". Additionally replace underscores with camel case.

RFC / to discuss if we should add "payable" modifier for SnarkyJS methods

Support async loading

Review existing precondition implementation for API usability

int64 support

Throw an error if a transaction fails

Currently transactions tend to fail silently, which is discovered later when an account is not available or a state update didn't happen

More useful errors in snarkyjs

• Include error strings in assertions somehow
• Don't throw arrays

Add keccak256 hash support

Write an RFC proposing a mechanism for showing the "compiled constraint system" ala godbolt

API to expose public key of caller in SnarkyJS methods

Make proving/verifying work in SnarkyJS with kimchi

Make more user friendly to use in a Snapp UI

[BUG] Mina.LocalBlockchain() allows multiple snapps to share an address and state

It appears that multiple snapps can be deployed to the same address using snarkyjs v0.1.11 and LocalBlockchain().
The second deployment transaction doesn't fail silently, it actually executes and allows an outsider to overwrite the existing state.

I made a small proof of concept for this bug here: https://gist.github.com/mirceanis/b53b6acd0dbe6f1658c78706800736d5, based on one of the exercises from the workshop.

1. deploy contract1 with initial state and logic to snappPublicKey
   • everything runs normally
2. deploy contract2 to the same snappPublicKey
   • this should have failed but doesn't
   • It also works if the initial state is different, and existing state gets overridden
   • also, it doesn't matter if it's the same account performing the deployment. An external party can also do it.
3. existing state of the old contract is overridden by the new initial state of the new contract
   • this should not even be possible if 2. is fixed
4. execute code from contract2, works and updates the state
   • also should not work if 2. is fixed, but I thought I'd mention it since it may be related.
5. execute code from contract1 still works, with old contract logic, but over the new state
   • this is even weirder, since the new contract is not an "upgrade", but rather a "sibling" of the same address, sharing the same state

I suppose this is only an issue with the mock local blockchain, but I can't test the real thing yet :)

Even so, I believe that fixing this bug is important even before testnet snapps, since it should make it clearer to devs which parts of the code actually matter for circuits and building the security model of snapps.

Make chrome/web and node/server consistent

Code style clean-up

Whenever there is time, I'd like to go through the code base to address the following stylistic points (copied from the discussion on PR #36)

• scan the code base for usage of promises that can be simplified / made more readable by using async / await
• don't use type annotations in assignments or function return signature, except where necessary
• Classes which don't have instance methods should just be types instead. That removes the need for a constructor and makes the code less painful.
• It would be less confusing to me if "signatureSufficient" would instead be called "proofNecessary", and the Bool negated (if that's accurate)
• IMO it's easier to understand the purpose of a file if all its exports are listed at the very top (after the imports)
• (TBD) I'm not a fan of having many names for the same types / classes

Enable calling other snapps, creating accounts, ...

and deploying snapps from within a snapp.

Also, fix weird 3-way account interaction in the current examples when funding a snapp account.

This is a nice-to-have in the current mocked-blockchain situation, but a must-have once testnet is available.

Change the build to output 4 artifacts

• prover.js
• prover.key
• verifier.js
• verifier.key

Refactor to use a deploy() method instead of constructor

Bug: toString() on Field/Bool doesn't work outside of asProver blocks

It could work everywhere

Fix weird 3-way account interaction...

...in the current examples when funding a snapp account.

Fetch snapp account state during execution

Finish `Int64` implementation