[PQ-Accounts] SHAKE hint and direct variants #1730
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,21 +2,71 @@ | |
|
|
||
| > **NOTE:** This document is better viewed at [https://docs.openzeppelin.com/contracts-cairo/api/account](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account) | ||
|
|
||
| This crate provides components for building account contracts that interact with the network. | ||
|
|
||
| - `AccountComponent` validates transactions from signatures over the | ||
| [STARK Curve](https://docs.starknet.io/architecture-and-concepts/cryptography/#the_stark_curve). | ||
|
|
||
| - `EthAccountComponent` validates transactions from signatures over the | ||
| [Secp256k1 curve](https://en.bitcoin.it/wiki/Secp256k1). | ||
|
|
||
| - `Falcon512AccountComponent` provides felt-array public-key management and account behavior for | ||
| canonical Falcon-512 public keys. It is generic over `Falcon512SignatureVerifier` and supports | ||
| two supplied SHAKE-256 strategies: | ||
|
|
||
| - `Falcon512ShakeVerifier` validates a 60-felt signature containing a verifier-checked | ||
| polynomial-product hint to reduce on-chain execution cost. | ||
|
|
||
| - `Falcon512ShakeDirectVerifier` validates a 31-felt signature and recomputes the polynomial | ||
| product on-chain. | ||
|
|
||
| > **WARNING:** The supplied Falcon verifiers target the verification relation and SHAKE-256 | ||
| > hash-to-point from the FALCON submission selected by NIST. Their public-key and signature | ||
| > encodings are contract-specific, and they are not FN-DSA (FIPS 206) implementations. | ||
|
|
||
| The Falcon component implements invoke, declare, and deploy-account validation, | ||
| signature validation, and owner-authorized felt-array public-key management. Contracts embed it | ||
| with `SRC5Component` and one of the supplied verifier strategies. Ready-to-deploy variants with | ||
| SRC9 outside execution and class upgrades are provided by the `openzeppelin_presets` package. | ||
|
|
||
| Falcon accounts support owner-authorized key rotation by executing a self-call to | ||
| `set_public_key` or `setPublicKey`. As with the STARK-curve and Secp256k1 accounts, the | ||
| current key authorizes the outer account transaction and the new key signs a | ||
| domain-separated ownership-acceptance message. Rotation keeps the same account address. | ||
| Because the current key authorizes the outer transaction, rotating a lost or unavailable key | ||
| requires an independent recovery mechanism. The upgradeable presets can adopt verifier changes at | ||
| the same account address through a self-authorized class upgrade. | ||
|
|
||
| ### Build profile | ||
|
|
||
| Build deployable Falcon preset artifacts from this repository with | ||
| `scarb --release build -p openzeppelin_presets`. The workspace dev profile produces Falcon Sierra | ||
| artifacts that cannot be lowered to CASM. Only the workspace's `target/release` Falcon preset | ||
| artifacts are suitable for declaration. A consuming project that embeds the component must | ||
| likewise use a declaration profile with inlining enabled. | ||
|
|
||
| ### Maintainer workflow: generated Falcon NTT sources | ||
|
|
||
| The Falcon root tables, bit-reversal table, and unrolled production transform are derived and | ||
| checked by `scripts/falcon_512/generate_ntt.py`. Regenerate them from the repository root and verify | ||
| the checked-in output with: | ||
|
|
||
| ```sh | ||
| python3 scripts/falcon_512/generate_ntt.py --write | ||
| git diff --exit-code -- packages/account/src/falcon_512/ntt | ||
| ``` | ||
|
|
||
| ### Interfaces | ||
|
|
||
| - [`ISRC6`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#ISRC6) | ||
| - [`IFeltArrayDeployable`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#IFeltArrayDeployable) | ||
|
Collaborator
There was a problem hiding this comment. Severity 2 — Low: broken doc links and misplaced maintainer content.
|
||
| - [`IFeltArrayPublicKey`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#IFeltArrayPublicKey) | ||
| - [`IFeltArrayPublicKeyCamel`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#IFeltArrayPublicKeyCamel) | ||
| - [`ISRC9_V2`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#ISRC9_V2) | ||
|
|
||
| ### Components | ||
|
|
||
| - [`AccountComponent`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#AccountComponent) | ||
| - [`EthAccountComponent`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#EthAccountComponent) | ||
| - [`Falcon512AccountComponent`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#Falcon512AccountComponent) | ||
| - [`SRC9Component`](https://docs.openzeppelin.com/contracts-cairo/3.x/api/account#SRC9Component) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| // SPDX-License-Identifier: MIT | ||
| // OpenZeppelin Contracts for Cairo v4.0.0-alpha.1 (account/src/falcon_512.cairo) | ||
|
|
||
| //! Falcon-512 SHAKE account component and verifier strategies. | ||
| //! | ||
| //! `Falcon512ShakeVerifier` validates the FALCON submission relation with a verifier-checked | ||
| //! polynomial-product hint that reduces on-chain execution cost. `Falcon512ShakeDirectVerifier` | ||
| //! recomputes the product on-chain. Both strategies use SHAKE-256 hash-to-point and | ||
| //! contract-specific felt encodings; they are not FN-DSA (FIPS 206) implementations. | ||
| //! | ||
| //! `Falcon512AccountComponent` provides SRC6 account behavior and owner-authorized key rotation | ||
| //! for canonical packed Falcon-512 public keys. Ready-to-deploy compositions are provided by the | ||
| //! `openzeppelin_presets` package. | ||
|
|
||
| pub mod account; | ||
| pub(crate) mod falcon; | ||
| pub(crate) mod hashing; | ||
| pub(crate) mod ntt; | ||
| pub(crate) mod packing; | ||
| pub mod verifier; | ||
| pub mod verifier_impls; | ||
| pub(crate) mod zq; | ||
|
|
||
| pub use account::Falcon512AccountComponent; | ||
| pub use verifier::Falcon512SignatureVerifier; | ||
| pub use verifier_impls::{Falcon512ShakeDirectVerifier, Falcon512ShakeVerifier}; |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Severity 2 — Low: CI runs the expensive Falcon suite redundantly.
The 65 dev-profile Falcon tests run twice (here and in the coverage run at line 67), several above 1e9 L2 gas, serial in one job — and the coverage run doesn't enable
falcon_presets_tests, so the Falcon presets (SRC9 routing,upgrade'sassert_only_self) report as entirely untested in Codecov anyway. Two further cost sinks:test_fast_ntt_matches_generic_reference_for_every_basis_vectoralone costs 7.65B gas (~76M steps) and is single-handedly why the 100M step cap is needed (the boundary/pseudorandom test already covers the interesting cases — sample every 16th basis vector or feature-gate it); and the#[cfg(test)]felt wrapper re-inlines the 31k-statement NTT body, making ~26.7% of the test program duplicate code and a 44 MB test artifact (have it callntt_falcon512_fast_u16_uncheckedand convert instead).