docs: update CHANGELOG with breaking changes since v1.2.0 (#1732)

# Update CHANGELOG with breaking changes since v1.2.0

This PR updates the CHANGELOG.md file to document all breaking interface
changes between tag v1.2.0 and the current main branch, following the
Keep a Changelog format.

## Changes Made

- Added comprehensive [Unreleased] section documenting breaking changes
in CLI, SDK, and Library Interfaces
- Included migration guides for each category of breaking changes
- Preserved existing version history while updating format to follow
Keep a Changelog convention

## Breaking Changes Documented

### CLI
- New `init` command for project initialization
- New `commit` command for viewing executable commits
- Setup command renamed from `EvmProvingSetupCmd` to `SetupCmd`
- All CLI commit outputs now consistently formatted in hexadecimal
- Prove command now uses binary name for default output file paths

### SDK
- Import path change for `DEFAULT_MAX_NUM_PUBLIC_VALUES`
- Configuration structure updates in `AggregationTreeConfig`

### Library Interfaces
- Major guest bindings refactor removing guest library components from
this repository
- Impact on benchmarks and examples that depend on guest libraries

## Complete Commit List (v1.2.0 to main)

* chore(ecc-guest): placeholder trait and function implementations for
patch compilation (#1720) (Jonathan Wang)
* docs: update division typo in ISA.md (#1726) (stephenh-axiom-xyz)
* chore: macro crate should use workspace version (#1723) (Jonathan
Wang)
* fix(cli): generate `openvm_init.rs` before building (#1721) (Jonathan
Wang)
* docs: Add comment explaining the `is_identity` optimization (#1716)
(Avaneesh-axiom)
* fix(sw-macro): host `set_up_once` undefined (#1717) (Jonathan Wang)
* chore: change to dual license (#1713) (Yi Sun)
* chore(ci): patch examples to use local crates (#1712) (Jonathan Wang)
* fix(ci): remove hashFiles from guest-lib-tests (#1710) (Jonathan Wang)
* chore(ecc-guest): remove `k256, p256` modules and fix guest-libs to
allow patching (#1708) (Jonathan Wang)
* chore: move directory (Jonathan Wang)
* feat: optimize `Group::is_identity` (#1709) (Avaneesh-axiom)
* chore: update workspace to v1.2.1-rc.0 (Jonathan Wang)
* perf(ecc-guest): optimize setup handling in ecc guest bindings (#1706)
(Jonathan Wang)
* perf: update stark-backend commit (Jonathan Wang)
* feat: Patch ecdsa `VerifyingKey::recover_from_prehash` to skip message
verification (#1691) (Avaneesh-axiom)
* refactor: guest bindings (#1613) (Jonathan Wang)
* refactor: guest bindings (#1613) (Avaneesh-axiom)
* feat: ensure all CLI commit outputs are in hex + fix verify STARK
(#1697) (stephenh-axiom-xyz)
* feat: CLI prove use bin name for output path + e2e stark verify
(#1675) (stephenh-axiom-xyz)
* feat: init command for cargo openvm (#1670) (stephenh-axiom-xyz)
* feat: commit command for cargo openvm (#1667) (stephenh-axiom-xyz)
* feat: cargo CLI update target directory (#1662) (stephenh-axiom-xyz)
* chore: add entry point to book examples without openvm::init!()
(#1663) (stephenh-axiom-xyz)
* docs: add CHANGELOG.md (#1660) (HrikB)
* fix: verifier read dir (#1658) (HrikB)
* refactor: CLI Build & Setup (#1649) (Xinding Wei)
* feat: helper functions for verify_openvm_stark (#1631) (Xinding Wei)
* feat: Macro define_verify_openvm_stark  (#1620) (Xinding Wei)
* feat: Root Verifier ASM (#1615) (Xinding Wei)
* feat: Add Rv32HintLoadByKey (#1606) (Xinding Wei)
* feat: Add e2e stark proof support (#1597) (Xinding Wei)
* feat: openvm build can build multiple targets + additional cargo
options (#1647) (stephenh-axiom-xyz)
* chore: update `getrandom` to v0.3 in `openvm` lib (#1635) (Jonathan
Wang)
* feat: Lazily call setup function for moduli and curves on first use
(#1603) (Avaneesh-axiom)
* feat: Build script for calling init macros (#1596) (Avaneesh-axiom)
* refactor: ELF and Program (#1638) (Xinding Wei)

Fixes INT-4185

---

**Link to Devin run**:
https://app.devin.ai/sessions/75c7bcb2466641609349ad3d02c31edd

**Requested by**: Jonathan Wang

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Jonathan Wang <[email protected]>
Co-authored-by: Jonathan Wang <[email protected]>
Co-authored-by: Tim Hwang <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+All notable changes to OpenVM will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project follows a versioning principles documented in [VERSIONING.md](./VERSIONING.md).
+
+## v1.3.0 (2025-07-14)
+
+No circuit constraints or verifying keys were changed in this release.
+
+A substantial refactor has been done to the guest libraries to separate the low level Rust bindings for OpenVM intrinsic instructions from the higher level user interface. For each VM extension, the `openvm-$name-guest` crate is now a _primitives library_ containing only the Rust bindings for the intrinsic instructions and essential logic related to the extension (e.g., ECDSA signature verification). We introduce new _guest libraries_ as standalone Rust crates which provide the high-level interfaces guest programs should use to interact with the associated VM extensions.
+
+Users are advised to switch to using the new guest libraries.
+
+### Added
+- (ISA) Added OpenVM phantom sub-instructions `HintNonQr` and `HintSqrt` to the algebra (modular arithmetic) extension. Added corresponding RISC-V custom instructions `hint_non_qr` and `hint_sqrt`.
+- (Guest Libraries) We introduce the following new guest libraries:
+  - `openvm-keccak256`: guest library for the Keccak256 hash function.
+  - `openvm-sha2`: guest library providing access to a set of accelerated SHA-2 family hash functions. Currently, the SHA-256 hash function is supported.
+  - `openvm-pairing`: guest library for the elliptic curve pairing check operation.
+  - `ff_derive`: patch of [ff_derive](https://crates.io/crates/ff_derive) using the algebra extension.
+  - `k256`: patch of [k256](https://crates.io/crates/k256) using the algebra and ECC extensions.
+  - `p256`: patch of [p256](https://crates.io/crates/p256) using the algebra and ECC extensions.
+  - `ruint`: patch of [ruint](https://crates.io/crates/ruint) using the big integer extension.
+  - `openvm-verify-stark`: a new guest library providing a `define_verify_stark_proof!` macro which generates a user-named function `$verify_stark` that can be used to verify an OpenVM STARK proof from within a Rust program. The `$verify_stark` function is accelerated using the native field arithmetic extension.
+- (CLI) New `cargo openvm init` and `cargo openvm commit` commands.
+- (CLI) New `cargo openvm prove stark` and `cargo openvm verify stark` commands to generate a single final STARK proof without Halo2 SNARK wrapper.
+- (SDK) New functions `generate_e2e_stark_proof` and `verify_e2e_stark_proof`
+
+### Changed
+- (Primitives Libraries) In the algebra and elliptic curve primitive libraries, the `setup_*` functions have been removed from guest bindings and are now called on-demand within other relevant binding functions. Additionally, custom opcode initialization is now simplified through the inclusion of `openvm_init.rs` files and the `openvm::init!()` macro. Read the book for more details.
+- (CLI) The build command `cargo openvm build` now stores build artifacts in the `target/` to match cargo conventions.
+- (CLI) The `cargo openvm setup` command now supports skipping halo2 proving keys and outputs halo2 PK and STARK PK as separate files.
+- (CLI) The `cargo openvm commit` and `cargo openvm prove stark` commands now consistently output commit values in hexadecimal format.
+- (CLI) The `cargo openvm prove` command now outputs proofs to `${bin_name}.app.proof` instead of `app.proof`.
+
+### Removed
+- (ISA) Removed OpenVM phantom sub-instructions `HintDecompress` and `HintNonQr` from the elliptic curve extension. Removed corresponding RISC-V custom instructions `hint_decompress` and `hint_non_qr`.
+
+## v1.2.0 (2025-06-02)
+
+### Security Fixes
+This release makes fixes for security advisories:
+- Plonky3: https://github.com/Plonky3/Plonky3/security/advisories/GHSA-f69f-5fx9-w9r9
+- OpenVM: https://github.com/openvm-org/openvm/security/advisories/GHSA-4w7p-8f9q-f4g2 (recursion circuit fixes corresponding to Plonky3)
+
 ## v1.1.2 (2025-05-08)
 
 - The solidity verifier contract no longer has any awareness of the OpenVM patch version. `{MAJOR_VERSION}.{MINOR_VERSION}` is the minimum information necessary to identify the verifier contract since any verifier contract changes will be accompanied by a minor version bump.

crates/toolchain/custom_insn/src/lib.rs

@@ -340,7 +340,7 @@ pub fn custom_insn_r(input: proc_macro::TokenStream) -> proc_macro::TokenStream
 /// This macro is used to define custom I-type RISC-V instructions for the zkVM.
 /// Usage:
 /// ```rust
-/// custom_insn_r!(
+/// custom_insn_i!(
 ///     opcode = OPCODE,
 ///     funct3 = FUNCT3,
 ///     rd = InOut x0,