starknet_api: add PROOF_VERSION_V1 and accept either marker in ProofFactsVariant

[Yoni-Starkware]

No description provided.

[cursor]

PR Summary

Medium Risk
Extends transaction proof-facts parsing/validation to accept a new version marker and changes SnosProofFacts.proof_version from a raw Felt to a typed ProofVersion, which could affect clients constructing or validating proof facts.

Overview
Adds a new proof-facts version marker PROOF_VERSION_V1 and introduces a typed ProofVersion enum to represent supported proof versions.

Updates ProofFactsVariant::try_from / SnosProofFacts to accept either PROOF0 or PROOF1 as the first proof-facts field (with improved error messaging), and adjusts downstream test utilities to emit the marker via ProofVersion::as_felt(). Includes new unit tests to cover accepted/rejected proof versions and short-string encoding.

^{Reviewed by Cursor Bugbot for commit fa20920. 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

[Yoni-Starkware]

• workspace,starknet_proof_verifier: bump privacy-{prove,circuit-verify} to 69ed219, add legacy alias #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());
}