docs: zkir v3 known issues for the release

CHANGELOG.md

@@ -16,6 +16,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking:** Verify `ShieldedMultiSigV2` and `ShieldedMultiSigV3` approvals with `secp256k1EcdsaVerifyLowS` from the new `crypto/Ecdsa` module, removing `stubVerifySignature` from both presets. `execute` / `mint` / `burn` now take `Vector<2, Secp256k1Point>` public keys and `Vector<2, Secp256k1EcdsaSignature>` signatures, and signer commitments hash the public-key coordinates (`pkX`, `pkY`) instead of a `Bytes<64>` key. `ShieldedMultiSigV2`'s `execute` digest is now domain-separated and bound to the contract instance (`kernel.self()`) and the full recipient (kind and address). Both presets share the verification logic through the new `EcdsaSignerManager` module, which unifies the signer-commitment domain separator on `multisig:signer:`; `ShieldedMultiSigV2` previously used `MultiSig:signer:`, so its commitments change again. The module owns the instance salt and the signer registry, so `ShieldedMultiSigV3`'s `ledger()` reader no longer exposes `_instanceSalt`, and `ShieldedMultiSigV2` no longer exports the `VerificationState` and `SignerCommitmentInput` structs, which were part of its generated artifact types. These primitives require ZKIR v3, so `compile:multisig` now passes `--feature-zkir-v3`. (#826)
 - Upgrade the Compact toolchain and Midnight dependencies: compiler `0.31.0` → `0.34.0`, `@midnight-ntwrk/compact-runtime` `0.16.0` → `0.19.0`, `@midnight-ntwrk/ledger-v8` `8.1.0` → `@midnightntwrk/ledger-v9` `1.0.0-rc.3`, `@midnight-ntwrk/compact-js` `2.5.1` → `2.5.5-rc.8`, the `midnight-js` packages `4.1.1` → `5.0.0-beta.7`, and `@openzeppelin/compact-simulator` `^0.3.1` → `^0.4.0`. Contract `pragma language_version` raised `>= 0.23.0` → `>= 0.26.0` (the language version shipped with compiler 0.34.0). (#841)
 
+### Known issues
+
+- Compiler 0.34.0 emits ZKIR v2 by default, and this release targets v2. Only `crypto/Ecdsa`, `multisig/EcdsaSignerManager` and the `ShieldedMultiSigV2` / `ShieldedMultiSigV3` presets need `--feature-zkir-v3`, because the `Secp256k1` types live in the v3 library; `compile:crypto` and `compile:multisig` pass it.
+- Under `--feature-zkir-v3`, any impure circuit that reaches `ElGamal.encryptPoint` (notably `ConfidentialFungibleToken`) fails at key generation with `Unsupported test_eq: JubjubScalar == JubjubScalar`, because the ZKIR v3 backend has no `JubjubScalar` equality ([LFDT-Minokawa/compact#757](https://github.com/LFDT-Minokawa/compact/issues/757)). A source-level fix, comparing the derived point instead of the scalar, lands in the next release.
+- Under `--feature-zkir-v3`, exporting `ElGamal.derivePk` as an impure circuit panics with `ZkStdLibArch must enable jubjub` ([LFDT-Minokawa/compact#616](https://github.com/LFDT-Minokawa/compact/issues/616)). There is no source workaround.
+- `@openzeppelin/compact-cli` `0.0.3` pins `@openzeppelin/compact-builder` to `0.0.4`, which reports a failed compile as success on Linux and writes no artifact. This is fixed in `compact-builder` `0.0.5` ([OpenZeppelin/compact-tools#162](https://github.com/OpenZeppelin/compact-tools/pull/162)); a `compact-cli` patch release picking it up follows, after which this repo bumps it. Until then, check that `artifacts/<Name>/compiler/contract-info.json` exists after a compile.
+
 ## 0.3.0-alpha.2 (2026-08-11)
 
 ### Changed

README.md

@@ -189,6 +189,12 @@ Compiling 14 circuits:
 Overall progress [====================] 14/14
 ```
 
+ZKIR v3: the library targets ZKIR v2, the compiler 0.34.0 default. Pass
+`--feature-zkir-v3` only when the contract imports the secp256k1-based modules
+(`crypto/Ecdsa`, `multisig/EcdsaSignerManager`, `ShieldedMultiSigV2`,
+`ShieldedMultiSigV3`). Compiling the other modules under v3 currently hits
+upstream blockers, listed under [Known issues](CHANGELOG.md#known-issues).
+
 ## Development
 
 OpenZeppelin Contracts for Compact exists thanks to its contributors.