A few weeks ago, we unveiled o1js v2.0—the latest major release in o1js' lifecycle—following an extensive external audit. This release builds on the momentum from earlier this year, when we launched v1.0 alongside Mina's Berkeley hard fork. The first major release marked a key step in making zkApps production-ready and deployable on mainnet. Now, with v2.0, we’re enhancing o1js to refine and strengthen the framework that developers can rely on and build on.
Overview of o1js v2.0
The changes in v2.0 were heavily focused on internal circuit structure, driving improvements in constraints—a mathematical representation of your application’s source code and a core aspect of how zkApps function. This rewrite of our circuits was necessary to implement deeper security measures and address compatibility-breaking issues. Many of these were influenced by findings from an external audit by Veridise, which provided valuable insights to further strengthen o1js. These were first implemented in v1.0, but with this major release are now backwards-compatible in v2.0.
Highlights of Key Fixes and Security Enhancements
Custom Token Balance Validation
One key update was a correction in how o1js processes custom token balances. In the audit, Veridise identified an issue where, in specific cases, certain AccountUpdate flags weren’t being considered fully, which could impact the balance calculation of custom tokens. To address this, we enhanced our validation checks to ensure these flags are consistently and accurately validated. The fix was initially introduced as a hotfix in v1.0, allowing us to mitigate any immediate risk without breaking existing zkApps. However, the full solution, applied deeper in the circuit’s core, means v2.0 has a definitive, lasting fix.
For technical details, see the update here.
ECDSA and Foreign Curve Improvements
Another significant update involves our ECDSA and foreign curve support. We identified and addressed an issue related to the canonical ordering of the Signature class. Veridise flagged this as a medium-severity issue, as it could lead to signatures being incorrectly verified as valid. In response, we implemented an additional assertion to enforce the expected order, ensuring accuracy and consistency across verifications. As with the token balance fix, we released an initial fix for ECDSA in v1.0, creating new createForeignCurveV2() and createEcdsaV2() functions that developers could adopt immediately. With the release of v2.0, these safer, optimized v2 functions are now the default, and the deprecated versions have been removed.
Read more on the specific fixes here and here.
New Features and Enhancements
Beyond security, o1js v2.0 brings new features to help developers build with greater flexibility:
- Auxiliary Output Support for ZkProgram: Developers can now use auxiliary output as an additional data point in circuits. Auxiliary output can be thought of as an additional output returned for your circuit that the developer can then use to do other computations with. As opposed to public output, which is required by the verifier to verify the proof, auxiliary output is not part of the proof and is not needed by the verifier to verify the proof’s correctness - it's a nice quality of life improvement that will make it easier for developers to build large, complex and modular applications using
zkProgram. - BLAKE2B Hashing Support: o1js v2.0 introduces support for the BLAKE2B cryptographic hash function, similar to SHA256, Keccak, or Poseidon. This adds a new tool for zkApp developers who require this versatile hashing option. This feature expands o1js’s cryptographic capabilities, supporting more use cases across various applications.
Ongoing Maintenance for o1js v1.0
We advise all developers to upgrade to o1js v2.0. The upgrade to the latest version should be fast - pretty much all APIs (except a few) stayed the same - so it’s just a matter of running npm i o1js and continuing to build your application. With o1js v2.0, your application will be more secure and have access to more features. However, please keep in mind that upgrading your project to o1js v2.0 will break the constraints of your application. This means that if you have already deployed your application to Mina mainnet or devnet, your project with o1js 2.0 will not be able to interact with these deployed applications - you will have to redeploy them if you choose to upgrade.
Going forward, we plan to support o1js v1.0 until the next hard fork on Mina Protocol. This support will be essential maintenance, mostly including critical bug fixes and security patches. After that, our focus will be on o1js v2.0 and its subsequent versions.
How do I Upgrade?
Upgrading your application to o1js v2.0 is straightforward with just two main changes to keep in mind. First, you'll need to update your function names - this means removing any "V2" suffixes (for example, changing functionNameV2() to just functionName()), and using the new names for completely renamed functions (like switching from AccountUpdate.defaultAccountUpdate to AccountUpdate.default).
The second change affects ZkPrograms: you'll need to adjust how you handle return values. When returning public output, wrap it in an object (change return Field(1); to return { publicOutput: Field(1) };), and when working with proofs, you'll need to destructure them (instead of let proof = await MyProgram.baseCase(), use let { proof }: { proof: Proof<Empty, Field> } = await MyProgram.baseCase()).
That's all there is to it - your application should now be fully compatible with o1js v2.0!
Looking Ahead
With o1js v2.0, we’re proud to bring developers a more robust framework that not only strengthens the security of zkApps but also expands the toolkit available for innovative cryptographic applications. This release is a testament to our commitment to evolving o1js alongside the needs of Mina’s developer ecosystem—ensuring that every update not only addresses security but also introduces new capabilities that allow you to push the boundaries of what zkApps can achieve.
As we continue building o1js, our focus remains on supporting you, the developer community, with the tools and resources to create powerful, secure, and flexible zkApps. We’re excited to see how v2.0 will empower your projects and drive new possibilities within Mina and beyond. For any questions or assistance with upgrading, don’t hesitate to reach out to our team on the Mina Discord, and for a full list of changes and improvements, see the changelog here.