libid-contracts 0.11.0

//! The ceremony circuits' UltraHonk verifiers: which circuit each platform
//! proves under, and a deploy that links the libraries a bb verifier needs.
//!
//! A Honk verifier is not written in this repository. bb derives it from a
//! circuit's verification key, `libid-circuits` runs bb and ships the
//! Solidity in its release tarballs, and `scripts/vendor-circuit-verifiers.sh`
//! downloads the pinned release — checked against digests committed in
//! `solidity/contracts/circuits/circuits.json` — formats it and writes it
//! under `solidity/contracts/circuits`, gitignored and vendored again before
//! every build. From there it is a contract like any other: `forge build`
//! compiles it and `scripts/vendor-artifacts.sh` embeds it, so a consumer
//! deploys it from [`Artifacts::embedded`] with no `bb`.
//!
//! bb emits `RelationsLib` and `ZKTranscriptLib` as external libraries, so a
//! verifier's creation code carries a placeholder per call site until each
//! library is deployed and its address linked in. [`deploy_honk_verifier`]
//! does all of that and returns the verifier's address, which is what a
//! [`platform_verifier::Initializer`](crate::platform_verifier::Initializer)
//! pins — by address and by the code hash it reads off the chain.

use alloy::{
    primitives::Address,
    providers::Provider,
};

use crate::{
    artifacts::Artifacts,
    deploy::deploy_contract_from,
    error::{
        Error,
        Result,
    },
};

/// One ceremony circuit, and so one vendored Honk verifier.
///
/// Two, not three: `oidc-google` proves the Google ID Token, and
/// `bearer-link` ties a token exchange to an identity for X and GitHub
/// alike, because their statements are the same.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Circuit {
    /// The token-exchange circuit, shared by the `x/v1` and `github/v1`
    /// profiles.
    BearerLink,
    /// The Google OIDC circuit, for `google/v1`.
    OidcGoogle,
}

impl Circuit {
    /// Every circuit the launch platforms verify under.
    pub const ALL: [Self; 2] = [Self::BearerLink, Self::OidcGoogle];

    /// The circuit's directory in the `libid-circuits` release, which is
    /// also its tarball's name and its key in `circuits.json`.
    pub const fn name(self) -> &'static str {
        match self {
            Self::BearerLink => "bearer-link",
            Self::OidcGoogle => "oidc-google",
        }
    }

    /// The vendored contract, which is also its `.sol` file and its entry
    /// in [`COVERED`](crate::artifacts::COVERED). bb names every verifier
    /// `HonkVerifier`; `libid-circuits` renames each so two can share a
    /// project and one artifact path names one circuit.
    pub const fn contract(self) -> &'static str {
        match self {
            Self::BearerLink => "BearerLinkHonkVerifier",
            Self::OidcGoogle => "OidcGoogleHonkVerifier",
        }
    }
}

/// The external libraries every bb verifier links, vendored beside it under
/// its own `.sol` file (the shape `linkReferences` names them in).
pub const LIBRARIES: [&str; 2] = ["RelationsLib", "ZKTranscriptLib"];

/// The `libid-circuits` release the vendored verifiers came from, read from
/// the pin `scripts/vendor-artifacts.sh` copies in as `circuits.json`.
///
/// A Honk verifier IS its verification key, so a consumer that names a
/// deployment after its artifact — a CREATE3 name, say — wants this in the
/// name: a new circuits release is a different contract and must land at a
/// different address rather than silently replace the old one.
///
/// Errors for an [`Artifacts::from_dir`] over a raw forge `out/`, which
/// carries no pin.
pub fn version(artifacts: &Artifacts) -> Result<String> {
    let pin: serde_json::Value = artifacts.read_json("circuits.json")?;
    pin["version"]
        .as_str()
        .map(str::to_owned)
        .ok_or_else(|| Error::Artifact {
            detail: "circuits.json has no version".into(),
        })
}

/// Deploy `circuit`'s Honk verifier with its libraries linked, and return
/// its address.
///
/// Each library is deployed first and its address substituted into the
/// verifier's creation code, then the verifier itself; deploying the
/// placeholder would produce a contract that reverts on every proof. Three
/// transactions per circuit. The libraries are not shared between the two
/// circuits: each verifier's file carries its own copy, and forge links a
/// verifier only against the libraries of its own file.
///
/// The address is what a Platform Verifier initializer takes as
/// `honk_verifier`; the code hash it pins beside it is read off the chain by
/// [`Initializer::call`](crate::platform_verifier::Initializer::call).
///
/// `sender` opts into explicit nonce management (see
/// [`deploy_contract_from`]).
pub async fn deploy_honk_verifier<P: Provider>(
    provider: &P,
    artifacts: &Artifacts,
    circuit: Circuit,
    sender: Option<Address>,
) -> Result<Address> {
    let contract = circuit.contract();
    let bytecode = artifacts
        .linked_bytecode(provider, contract, contract, sender)
        .await?;
    deploy_contract_from(
        provider,
        bytecode,
        &format!("{contract} ({} circuit)", circuit.name()),
        sender,
    )
    .await
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::artifacts::COVERED;

    /// Every verifier and every library it links is one the crate vendors,
    /// under the verifier's own file — a library missing from the artifacts
    /// could only deploy with its placeholder left in.
    #[test]
    fn every_verifier_and_its_libraries_are_covered() {
        let artifacts = Artifacts::embedded();
        for circuit in Circuit::ALL {
            let contract = circuit.contract();
            assert!(
                COVERED.contains(&(contract, contract)),
                "{contract} is not in COVERED"
            );
            for library in LIBRARIES {
                assert!(
                    COVERED.contains(&(contract, library)),
                    "{contract}.sol:{library} is not in COVERED"
                );
            }

            // The artifact links exactly LIBRARIES, and nothing under another
            // file: a verifier that linked a library the list does not name
            // would deploy with a placeholder left in.
            let refs = artifacts.link_references(contract, contract).unwrap();
            let mut linked: Vec<(String, String)> = refs
                .iter()
                .flat_map(|(path, libs)| {
                    let stem = std::path::Path::new(path)
                        .file_stem()
                        .and_then(|s| s.to_str())
                        .unwrap_or_else(|| panic!("{contract}: bad library path {path}"))
                        .to_owned();
                    libs.as_object()
                        .into_iter()
                        .flatten()
                        .map(move |(name, _)| (stem.clone(), name.clone()))
                })
                .collect();
            linked.sort();
            let mut expected: Vec<(String, String)> = LIBRARIES
                .iter()
                .map(|lib| (contract.to_owned(), (*lib).to_owned()))
                .collect();
            expected.sort();
            assert_eq!(linked, expected, "{contract} links something else");
        }
    }

    /// The two circuits are distinct artifacts: a shared one would wire
    /// both platforms to one verification key.
    #[test]
    fn the_two_circuits_are_different_artifacts() {
        let artifacts = Artifacts::embedded();
        let [bearer, oidc] = Circuit::ALL;
        assert_ne!(bearer.contract(), oidc.contract());
        assert_ne!(
            artifacts
                .bytecode_hex(bearer.contract(), bearer.contract())
                .unwrap(),
            artifacts
                .bytecode_hex(oidc.contract(), oidc.contract())
                .unwrap()
        );
    }

    /// The enum and the pin name the same circuits under the same
    /// contracts; the pin is what the vendor script follows, the enum what
    /// a consumer deploys by.
    #[test]
    fn the_enum_matches_the_pin() {
        let artifacts = Artifacts::embedded();
        let pin: serde_json::Value = artifacts.read_json("circuits.json").unwrap();
        let circuits = pin["circuits"].as_object().expect("circuits object");
        assert_eq!(circuits.len(), Circuit::ALL.len());
        for circuit in Circuit::ALL {
            let entry = &circuits[circuit.name()];
            assert_eq!(entry["contract"].as_str(), Some(circuit.contract()));
            let digest = entry["sha256"].as_str().expect("sha256 string");
            assert_eq!(digest.len(), 64, "{}: not a sha256", circuit.name());
        }
        let version = version(&artifacts).unwrap();
        assert!(
            version.split('.').count() == 3,
            "circuits.json version '{version}' is not major.minor.patch"
        );
    }
}