starknet_api: add PROOF_VERSION_V1 and accept either marker in ProofFactsVariant

[Yoni-Starkware]

No description provided.

[cursor]

PR Summary

Medium Risk
Changes transaction ProofFacts validation/parsing to accept a new version marker, which could affect client-side proving compatibility and rejection behavior for malformed inputs. Scope is small but touches consensus-adjacent validation logic.

Overview
Extends proof-facts versioning by introducing PROOF_VERSION_V1 and a new ProofVersion enum, and changing SnosProofFacts.proof_version from a raw Felt to this typed marker.

Updates ProofFactsVariant::try_from validation to accept either PROOF0 or PROOF1 as the first field (and improves the error message), updates blockifier tests to emit the version via as_felt(), and adds focused unit tests (fields_test.rs) covering supported/unsupported markers and string-to-felt encoding.

^{Reviewed by Cursor Bugbot for commit aeaaed1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[reviewable-StarkWare]

This change is 

[github-actions]

Artifacts upload workflows:

• Started at 2026-05-10T14:38:19Z
• Started at 2026-05-11T11:49:12Z
• Started at 2026-05-11T12:03:28Z
• Started at 2026-05-17T09:57:12Z

[Yoni-Starkware]

• workspace,starknet_proof_verifier: bump privacy-{prove,circuit-verify} to 039e52c, add v0/v1 aliases #14017
• starknet_proof_verifier: add v0.14.3 regression case for PROOF_VERSION_V1 fixture #14016
• starknet_api,starknet_proof_verifier: write PROOF_VERSION_V1 in try_into_proof_facts #14015
• apollo_starknet_os_program,starknet_os: support PROOF_VERSION_V1 in check_proof_facts #14014
• starknet_proof_verifier: accept either PROOF_VERSION_V0 or PROOF_VERSION_V1 in verify_proof #14013
• starknet_api: add PROOF_VERSION_V1 and accept either marker in ProofFactsVariant #14012 👈 (View in Graphite)
• starknet_api,starknet_proof_verifier: rename PROOF_VERSION to PROOF_VERSION_V0 #14011
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Yoni-Starkware]

@Yoni-Starkware made 1 comment.
Reviewable status: 0 of 1 files reviewed, 1 unresolved discussion.

---

crates/starknet_api/src/transaction/fields.rs line 824 at r1 (raw file):

#[cfg(test)]
mod tests {

Please read the rust style guide and more the test modules accordingly https://github.com/starkware-industries/code-quality/blob/main/style_guide/rust_style_guide.md

[Yoni-Starkware]

@Yoni-Starkware resolved 1 discussion.
Reviewable status: 0 of 2 files reviewed, all discussions resolved.

[AvivYossef-starkware]

@AvivYossef-starkware reviewed 2 files and all commit messages, and made 3 comments.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on Yoni-Starkware).

---

crates/starknet_api/src/transaction/fields.rs line 19 at r2 (raw file):

#[cfg(test)]
#[path = "fields_test.rs"]
mod fields_test;

Our convention is to put it in the transaction.rs file

Code quote:

#[cfg(test)]
#[path = "fields_test.rs"]
mod fields_test;

---

crates/starknet_api/src/transaction/fields.rs line 695 at r2 (raw file):

            return Err(StarknetApiError::InvalidProofFacts(format!(
                "Expected first field to be {} (PROOF_VERSION_V0) or {} (PROOF_VERSION_V1), but \
                 got {}",

We are going to see the hex here, and it's not clear

Code quote:

 {}

---

crates/starknet_api/src/transaction/fields_test.rs line 15 at r2 (raw file):

        Felt::from(0xC0FFEE_u64),
    ]))
}

can you use existing?

Code quote:

fn snos_proof_facts(proof_version: Felt) -> ProofFacts {
    ProofFacts(Arc::new(vec![
        proof_version,
        VIRTUAL_SNOS,
        Felt::from(0xABCD_u64),
        VIRTUAL_OS_OUTPUT_VERSION,
        Felt::from(0_u64),
        Felt::from(0xBEEF_u64),
        Felt::from(0xC0FFEE_u64),
    ]))
}

[AvivYossef-starkware]

@AvivYossef-starkware reviewed 3 files and all commit messages, and made 2 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on Yoni-Starkware).

---

crates/starknet_api/src/transaction/fields.rs line 677 at r3 (raw file):

        } else {
            Err(value)
        }

Why is the error type Felt?

Code quote:

        } else {
            Err(value)
        }

---

crates/starknet_api/src/transaction/fields_test.rs line 11 at r3 (raw file):

    facts
}

consider adding a test that Felt::from_str(Proof_Version::V0.as_str) == Proof_Version::V0.as_felt()

[Yoni-Starkware]

@Yoni-Starkware made 2 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on Yoni-Starkware).

---

crates/starknet_api/src/transaction/fields.rs line 19 at r2 (raw file):

Previously, AvivYossef-starkware wrote…

Our convention is to put it in the transaction.rs file

To put what? I see similar pattern in transaction.rs, transaction_hash.rs, serde_utils.rs...

---

crates/starknet_api/src/transaction/fields_test.rs line 15 at r2 (raw file):

Previously, AvivYossef-starkware wrote…

can you use existing?

Done?

[AvivYossef-starkware]

@AvivYossef-starkware made 1 comment.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on Yoni-Starkware).

---

crates/starknet_api/src/transaction/fields.rs line 19 at r2 (raw file):

Previously, Yoni-Starkware (Yoni) wrote…

To put what? I see similar pattern in transaction.rs, transaction_hash.rs, serde_utils.rs...

to what I thought our convention

[Yoni-Starkware]

@Yoni-Starkware made 2 comments.
Reviewable status: 0 of 32 files reviewed, 2 unresolved discussions (waiting on AvivYossef-starkware).

---

crates/starknet_api/src/transaction/fields.rs line 677 at r3 (raw file):

Previously, AvivYossef-starkware wrote…

Why is the error type Felt?

Done.

---

crates/starknet_api/src/transaction/fields_test.rs line 11 at r3 (raw file):

Previously, AvivYossef-starkware wrote…

consider adding a test that Felt::from_str(Proof_Version::V0.as_str) == Proof_Version::V0.as_felt()

Done.

[AvivYossef-starkware]

@AvivYossef-starkware reviewed 32 files and all commit messages, made 4 comments, and resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on Yoni-Starkware).

---

crates/starknet_api/src/transaction/fields.rs line 710 at r14 (raw file):

    /// Returns the proof version marker (first felt). `Felt::ZERO` for empty proof facts.
    pub fn proof_version_felt(&self) -> Felt {
        self.0.first().copied().unwrap_or_default()

Why is this the desired behavior? Is it possible that the proof version is missing, and in that case, does it represent version zero?
If not, consider returning an error instead

Code quote:

.unwrap_or_default()

---

crates/starknet_api/src/transaction/fields.rs line 750 at r14 (raw file):

                proof_version,
            ))
        })?;

You can use the new display impl

Code quote:

        let proof_version = ProofVersion::try_from(*proof_version).map_err(|()| {
            StarknetApiError::InvalidProofFacts(format!(
                "Expected first field to be {} ({}) or {} ({}), but got {}",
                ProofVersion::V0.as_felt(),
                ProofVersion::V0.as_str(),
                ProofVersion::V1.as_felt(),
                ProofVersion::V1.as_str(),
                proof_version,
            ))
        })?;

---

crates/starknet_api/src/transaction/fields_test.rs line 40 at r14 (raw file):

    padded[32 - bytes.len()..].copy_from_slice(bytes);
    Felt::from_bytes_be(&padded)
}

starknet_types_core::short_string::ShortString already provides this conversion (impl From for Felt).

Code quote:

/// Encodes a Cairo short-string into a felt (big-endian, right-aligned).
fn short_string_to_felt(s: &str) -> Felt {
    let bytes = s.as_bytes();
    assert!(bytes.len() <= 32, "short string exceeds felt width");
    let mut padded = [0u8; 32];
    padded[32 - bytes.len()..].copy_from_slice(bytes);
    Felt::from_bytes_be(&padded)
}

---

crates/starknet_api/src/transaction/fields_test.rs line 47 at r14 (raw file):

fn proof_version_str_encodes_to_felt(#[case] version: ProofVersion) {
    assert_eq!(short_string_to_felt(version.as_str()), version.as_felt());
}

Consider deriving EnumIter here and in every test that you case by variant

Code quote:

#[rstest]
#[case::v0(ProofVersion::V0)]
#[case::v1(ProofVersion::V1)]
fn proof_version_str_encodes_to_felt(#[case] version: ProofVersion) {
    assert_eq!(short_string_to_felt(version.as_str()), version.as_felt());
}

[Yoni-Starkware]

@Yoni-Starkware made 2 comments.
Reviewable status: 30 of 32 files reviewed, all discussions resolved (waiting on AvivYossef-starkware).

---

crates/starknet_api/src/transaction/fields.rs line 710 at r14 (raw file):

Previously, AvivYossef-starkware wrote…

Why is this the desired behavior? Is it possible that the proof version is missing, and in that case, does it represent version zero?
If not, consider returning an error instead

Actually that's an unnecessary refactor. It's used only once, right after a check that the proof facts are not empty. Reverted

---

crates/starknet_api/src/transaction/fields_test.rs line 40 at r14 (raw file):

Previously, AvivYossef-starkware wrote…

starknet_types_core::short_string::ShortString already provides this conversion (impl From for Felt).

Done

[AvivYossef-starkware]

@AvivYossef-starkware reviewed 2 files and all commit messages, and made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on Yoni-Starkware).