From 0943e534ee054fe78ce2cbbf3f6f5ed5df83d91b Mon Sep 17 00:00:00 2001 From: Jseam Date: Sat, 6 Apr 2024 01:33:06 +0800 Subject: [PATCH] docs: automated sphinx documentation for python bindings (#714) --------- Co-authored-by: dante <45801863+alexander-camuto@users.noreply.github.com> Co-authored-by: Ethan Cemer Co-authored-by: github-actions[bot] --- .github/workflows/pypi.yml | 15 + .github/workflows/tagging.yml | 36 +- .gitignore | 3 +- .python-version | 1 + .readthedocs.yaml | 26 ++ docs/python/build.sh | 2 + docs/python/requirements-docs.txt | 4 + docs/python/src/conf.py | 29 ++ docs/python/src/index.rst | 11 + pyproject.toml | 2 +- requirements.txt | 4 +- src/python.rs | 680 ++++++++++++++++++++++++++++-- 12 files changed, 773 insertions(+), 40 deletions(-) create mode 100644 .python-version create mode 100644 .readthedocs.yaml create mode 100755 docs/python/build.sh create mode 100644 docs/python/requirements-docs.txt create mode 100644 docs/python/src/conf.py create mode 100644 docs/python/src/index.rst diff --git a/.github/workflows/pypi.yml b/.github/workflows/pypi.yml index a942044b2..63f8c06c3 100644 --- a/.github/workflows/pypi.yml +++ b/.github/workflows/pypi.yml @@ -128,6 +128,7 @@ jobs: mv Cargo.lock Cargo.lock.orig sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" Cargo.lock.orig >Cargo.lock + - name: Install required libraries shell: bash run: | @@ -359,3 +360,17 @@ jobs: with: repository-url: https://test.pypi.org/legacy/ packages-dir: ./ + + doc-publish: + name: Trigger ReadTheDocs Build + runs-on: ubuntu-latest + needs: pypi-publish + steps: + - uses: actions/checkout@v4 + + - name: Trigger RTDs build + uses: dfm/rtds-action@v1 + with: + webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }} + webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }} + commit_ref: ${{ github.ref_name }} diff --git a/.github/workflows/tagging.yml b/.github/workflows/tagging.yml index dc07470c2..47ebff149 100644 --- a/.github/workflows/tagging.yml +++ b/.github/workflows/tagging.yml @@ -14,6 +14,40 @@ jobs: - uses: actions/checkout@v4 - name: Bump version and push tag id: tag_version - uses: mathieudutour/github-tag-action@v6.1 + uses: mathieudutour/github-tag-action@v6.2 with: github_token: ${{ secrets.GITHUB_TOKEN }} + + - name: Set Cargo.toml version to match github tag for docs + shell: bash + env: + RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }} + run: | + mv docs/python/src/conf.py docs/python/src/conf.py.orig + sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" docs/python/src/conf.py.orig >docs/python/src/conf.py + rm docs/python/src/conf.py.orig + mv docs/python/requirements-docs.txt docs/python/requirements-docs.txt.orig + sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" docs/python/requirements-docs.txt.orig >docs/python/requirements-docs.txt + rm docs/python/requirements-docs.txt.orig + + - name: Commit files and create tag + env: + RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }} + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + git fetch --tags + git checkout -b release-$RELEASE_TAG + git add . + git commit -m "ci: update version string in docs" + git tag -d $RELEASE_TAG + git tag $RELEASE_TAG + + - name: Push changes + uses: ad-m/github-push-action@master + env: + RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }} + with: + branch: release-${{ steps.tag_version.outputs.new_tag }} + force: true + tags: true diff --git a/.gitignore b/.gitignore index 9635e363c..bfc009a62 100644 --- a/.gitignore +++ b/.gitignore @@ -49,4 +49,5 @@ node_modules timingData.json !tests/wasm/pk.key !tests/wasm/vk.key -!tests/wasm/vk_aggr.key \ No newline at end of file +docs/python/build +!tests/wasm/vk_aggr.key diff --git a/.python-version b/.python-version new file mode 100644 index 000000000..171a6a93d --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.12.1 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..61a8fdcaf --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,26 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: ./docs/python/src/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: ./docs/python/requirements-docs.txt diff --git a/docs/python/build.sh b/docs/python/build.sh new file mode 100755 index 000000000..7a065a2c5 --- /dev/null +++ b/docs/python/build.sh @@ -0,0 +1,2 @@ +#!/bin/sh +sphinx-build ./src build \ No newline at end of file diff --git a/docs/python/requirements-docs.txt b/docs/python/requirements-docs.txt new file mode 100644 index 000000000..73634b85b --- /dev/null +++ b/docs/python/requirements-docs.txt @@ -0,0 +1,4 @@ +ezkl==0.0.0 +sphinx +sphinx-rtd-theme +sphinxcontrib-napoleon diff --git a/docs/python/src/conf.py b/docs/python/src/conf.py new file mode 100644 index 000000000..de6d98f72 --- /dev/null +++ b/docs/python/src/conf.py @@ -0,0 +1,29 @@ +import ezkl + +project = 'ezkl' +release = '0.0.0' +version = release + + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.napoleon', + 'sphinx_rtd_theme', +] + +autosummary_generate = True +autosummary_imported_members = True + +templates_path = ['_templates'] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/python/src/index.rst b/docs/python/src/index.rst new file mode 100644 index 000000000..c311e2945 --- /dev/null +++ b/docs/python/src/index.rst @@ -0,0 +1,11 @@ +.. extension documentation master file, created by + sphinx-quickstart on Mon Jun 19 15:02:05 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +ezkl python bindings +================================================ + +.. automodule:: ezkl + :members: + :undoc-members: \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 13a4a71b7..949b97e6b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["maturin>=0.14,<0.15"] +requires = ["maturin>=1.0,<2.0"] build-backend = "maturin" [tool.pytest.ini_options] diff --git a/requirements.txt b/requirements.txt index 26b647ac8..cd1526d35 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,7 @@ attrs==23.2.0 exceptiongroup==1.2.0 importlib-metadata==7.1.0 iniconfig==2.0.0 -maturin==1.5.0 +maturin==1.5.1 packaging==24.0 pluggy==1.4.0 pytest==8.1.1 @@ -11,4 +11,4 @@ typing-extensions==4.10.0 zipp==3.18.1 onnx==1.15.0 onnxruntime==1.17.1 -numpy==1.26.4 \ No newline at end of file +numpy==1.26.4 diff --git a/src/python.rs b/src/python.rs index 82d2ee420..98469557c 100644 --- a/src/python.rs +++ b/src/python.rs @@ -33,6 +33,7 @@ use tokio::runtime::Runtime; type PyFelt = String; +/// pyclass representing an enum #[pyclass] #[derive(Debug, Clone)] enum PyTestDataSource { @@ -51,14 +52,17 @@ impl From for TestDataSource { } } -/// pyclass containing the struct used for G1 +/// pyclass containing the struct used for G1, this is mostly a helper class #[pyclass] #[derive(Debug, Clone)] struct PyG1 { #[pyo3(get, set)] + /// Field Element representing x x: PyFelt, #[pyo3(get, set)] + /// Field Element representing y y: PyFelt, + /// Field Element representing y #[pyo3(get, set)] z: PyFelt, } @@ -134,39 +138,59 @@ impl pyo3::ToPyObject for PyG1Affine { } } -/// pyclass containing the struct used for run_args +/// Python class containing the struct used for run_args +/// +/// Returns +/// ------- +/// PyRunArgs +/// #[pyclass] #[derive(Clone)] struct PyRunArgs { #[pyo3(get, set)] + /// float: The tolerance for error on model outputs pub tolerance: f32, #[pyo3(get, set)] + /// int: The denominator in the fixed point representation used when quantizing inputs pub input_scale: crate::Scale, #[pyo3(get, set)] + /// int: The denominator in the fixed point representation used when quantizing parameters pub param_scale: crate::Scale, #[pyo3(get, set)] + /// int: If the scale is ever > scale_rebase_multiplier * input_scale then the scale is rebased to input_scale (this a more advanced parameter, use with caution) pub scale_rebase_multiplier: u32, #[pyo3(get, set)] + /// list[int]: The min and max elements in the lookup table input column pub lookup_range: crate::circuit::table::Range, #[pyo3(get, set)] + /// int: The log_2 number of rows pub logrows: u32, #[pyo3(get, set)] + /// int: The number of inner columns used for the lookup table pub num_inner_cols: usize, #[pyo3(get, set)] + /// string: accepts `public`, `private`, `fixed`, `hashed/public`, `hashed/private`, `polycommit` pub input_visibility: Visibility, #[pyo3(get, set)] + /// string: accepts `public`, `private`, `fixed`, `hashed/public`, `hashed/private`, `polycommit` pub output_visibility: Visibility, #[pyo3(get, set)] + /// string: accepts `public`, `private`, `fixed`, `hashed/public`, `hashed/private`, `polycommit` pub param_visibility: Visibility, #[pyo3(get, set)] + /// list[tuple[str, int]]: Hand-written parser for graph variables, eg. batch_size=1 pub variables: Vec<(String, usize)>, #[pyo3(get, set)] + /// bool: Rebase the scale using lookup table for division instead of using a range check pub div_rebasing: bool, #[pyo3(get, set)] + /// bool: Should constants with 0.0 fraction be rebased to scale 0 pub rebase_frac_zero_constants: bool, #[pyo3(get, set)] + /// str: check mode, accepts `safe`, `unsafe` pub check_mode: CheckMode, #[pyo3(get, set)] + /// str: commitment type, accepts `kzg`, `ipa` pub commitment: PyCommitments, } @@ -226,7 +250,7 @@ impl Into for RunArgs { #[pyclass] #[derive(Debug, Clone)] -/// Pyclass marking the type of commitment +/// pyclass representing an enum, denoting the type of commitment pub enum PyCommitments { /// KZG commitment KZG, @@ -273,7 +297,19 @@ impl FromStr for PyCommitments { } } -/// Converts a felt to big endian +/// Converts a field element hex string to big endian +/// +/// Arguments +/// ------- +/// felt: str +/// The field element represented as a string +/// +/// +/// Returns +/// ------- +/// str +/// field element represented as a string +/// #[pyfunction(signature = ( felt, ))] @@ -283,22 +319,45 @@ fn felt_to_big_endian(felt: PyFelt) -> PyResult { } /// Converts a field element hex string to an integer +/// +/// Arguments +/// ------- +/// felt: str +/// The field element represented as a string +/// +/// Returns +/// ------- +/// int +/// #[pyfunction(signature = ( - array, + felt, ))] -fn felt_to_int(array: PyFelt) -> PyResult { - let felt = crate::pfsys::string_to_field::(&array); +fn felt_to_int(felt: PyFelt) -> PyResult { + let felt = crate::pfsys::string_to_field::(&felt); let int_rep = felt_to_i128(felt); Ok(int_rep) } -/// Converts a field eleement hex string to a floating point number +/// Converts a field element hex string to a floating point number +/// +/// Arguments +/// ------- +/// felt: str +/// The field element represented as a string +/// +/// scale: float +/// The scaling factor used to convert the field element into a floating point representation +/// +/// Returns +/// ------- +/// float +/// #[pyfunction(signature = ( - array, + felt, scale ))] -fn felt_to_float(array: PyFelt, scale: crate::Scale) -> PyResult { - let felt = crate::pfsys::string_to_field::(&array); +fn felt_to_float(felt: PyFelt, scale: crate::Scale) -> PyResult { + let felt = crate::pfsys::string_to_field::(&felt); let int_rep = felt_to_i128(felt); let multiplier = scale_to_multiplier(scale); let float_rep = int_rep as f64 / multiplier; @@ -306,9 +365,23 @@ fn felt_to_float(array: PyFelt, scale: crate::Scale) -> PyResult { } /// Converts a floating point element to a field element hex string +/// +/// Arguments +/// ------- +/// input: float +/// The field element represented as a string +/// +/// scale: float +/// The scaling factor used to quantize the float into a field element +/// +/// Returns +/// ------- +/// str +/// The field element represented as a string +/// #[pyfunction(signature = ( -input, -scale + input, + scale ))] fn float_to_felt(input: f64, scale: crate::Scale) -> PyResult { let int_rep = quantize_float(&input, 0.0, scale) @@ -318,9 +391,20 @@ fn float_to_felt(input: f64, scale: crate::Scale) -> PyResult { } /// Converts a buffer to vector of field elements +/// +/// Arguments +/// ------- +/// buffer: list[int] +/// List of integers representing a buffer +/// +/// Returns +/// ------- +/// list[str] +/// List of field elements represented as strings +/// #[pyfunction(signature = ( buffer - ))] +))] fn buffer_to_felts(buffer: Vec) -> PyResult> { fn u8_array_to_u128_le(arr: [u8; 16]) -> u128 { let mut n: u128 = 0; @@ -379,9 +463,20 @@ fn buffer_to_felts(buffer: Vec) -> PyResult> { } /// Generate a poseidon hash. +/// +/// Arguments +/// ------- +/// message: list[str] +/// List of field elements represnted as strings +/// +/// Returns +/// ------- +/// list[str] +/// List of field elements represented as strings +/// #[pyfunction(signature = ( message, - ))] +))] fn poseidon_hash(message: Vec) -> PyResult> { let message: Vec = message .iter() @@ -402,12 +497,31 @@ fn poseidon_hash(message: Vec) -> PyResult> { } /// Generate a kzg commitment. +/// +/// Arguments +/// ------- +/// message: list[str] +/// List of field elements represnted as strings +/// +/// vk_path: str +/// Path to the verification key +/// +/// settings_path: str +/// Path to the settings file +/// +/// srs_path: str +/// Path to the Structure Reference String (SRS) file +/// +/// Returns +/// ------- +/// list[PyG1Affine] +/// #[pyfunction(signature = ( message, vk_path=PathBuf::from(DEFAULT_VK), settings_path=PathBuf::from(DEFAULT_SETTINGS), srs_path=None - ))] +))] fn kzg_commit( message: Vec, vk_path: PathBuf, @@ -442,12 +556,31 @@ fn kzg_commit( } /// Generate an ipa commitment. +/// +/// Arguments +/// ------- +/// message: list[str] +/// List of field elements represnted as strings +/// +/// vk_path: str +/// Path to the verification key +/// +/// settings_path: str +/// Path to the settings file +/// +/// srs_path: str +/// Path to the Structure Reference String (SRS) file +/// +/// Returns +/// ------- +/// list[PyG1Affine] +/// #[pyfunction(signature = ( message, vk_path=PathBuf::from(DEFAULT_VK), settings_path=PathBuf::from(DEFAULT_SETTINGS), srs_path=None - ))] +))] fn ipa_commit( message: Vec, vk_path: PathBuf, @@ -482,10 +615,19 @@ fn ipa_commit( } /// Swap the commitments in a proof +/// +/// Arguments +/// ------- +/// proof_path: str +/// Path to the proof file +/// +/// witness_path: str +/// Path to the witness file +/// #[pyfunction(signature = ( proof_path=PathBuf::from(DEFAULT_PROOF), witness_path=PathBuf::from(DEFAULT_WITNESS), - ))] +))] fn swap_proof_commitments(proof_path: PathBuf, witness_path: PathBuf) -> PyResult<()> { crate::execute::swap_proof_commitments_cmd(proof_path, witness_path) .map_err(|_| PyIOError::new_err("Failed to swap commitments"))?; @@ -494,11 +636,27 @@ fn swap_proof_commitments(proof_path: PathBuf, witness_path: PathBuf) -> PyResul } /// Generates a vk from a pk for a model circuit and saves it to a file +/// +/// Arguments +/// ------- +/// path_to_pk: str +/// Path to the proving key +/// +/// circuit_settings_path: str +/// Path to the witness file +/// +/// vk_output_path: str +/// Path to create the vk file +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( path_to_pk=PathBuf::from(DEFAULT_PK), circuit_settings_path=PathBuf::from(DEFAULT_SETTINGS), vk_output_path=PathBuf::from(DEFAULT_VK), - ))] +))] fn gen_vk_from_pk_single( path_to_pk: PathBuf, circuit_settings_path: PathBuf, @@ -520,10 +678,22 @@ fn gen_vk_from_pk_single( } /// Generates a vk from a pk for an aggregate circuit and saves it to a file +/// +/// Arguments +/// ------- +/// path_to_pk: str +/// Path to the proving key +/// +/// vk_output_path: str +/// Path to create the vk file +/// +/// Returns +/// ------- +/// bool #[pyfunction(signature = ( path_to_pk=PathBuf::from(DEFAULT_PK_AGGREGATED), vk_output_path=PathBuf::from(DEFAULT_VK_AGGREGATED), - ))] +))] fn gen_vk_from_pk_aggr(path_to_pk: PathBuf, vk_output_path: PathBuf) -> PyResult { let pk = load_pk::, AggregationCircuit>(path_to_pk, ()) .map_err(|_| PyIOError::new_err("Failed to load pk"))?; @@ -538,6 +708,17 @@ fn gen_vk_from_pk_aggr(path_to_pk: PathBuf, vk_output_path: PathBuf) -> PyResult } /// Displays the table as a string in python +/// +/// Arguments +/// --------- +/// model: str +/// Path to the onnx file +/// +/// Returns +/// --------- +/// str +/// Table of the nodes in the onnx file +/// #[pyfunction(signature = ( model = PathBuf::from(DEFAULT_MODEL), py_run_args = None @@ -553,7 +734,16 @@ fn table(model: PathBuf, py_run_args: Option) -> PyResult { } } -/// generates the srs +/// Generates the Structured Reference String (SRS), use this only for testing purposes +/// +/// Arguments +/// --------- +/// srs_path: str +/// Path to the create the SRS file +/// +/// logrows: int +/// The number of logrows for the SRS file +/// #[pyfunction(signature = ( srs_path, logrows, @@ -564,7 +754,26 @@ fn gen_srs(srs_path: PathBuf, logrows: usize) -> PyResult<()> { Ok(()) } -/// gets a public srs +/// Gets a public srs +/// +/// Arguments +/// --------- +/// settings_path: str +/// Path to the settings file +/// +/// logrows: int +/// The number of logrows for the SRS file +/// +/// srs_path: str +/// Path to the create the SRS file +/// +/// commitment: str +/// Specify the commitment used ("kzg", "ipa") +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( settings_path=PathBuf::from(DEFAULT_SETTINGS), logrows=None, @@ -597,7 +806,23 @@ fn get_srs( Ok(true) } -/// generates the circuit settings +/// Generates the circuit settings +/// +/// Arguments +/// --------- +/// model: str +/// Path to the onnx file +/// +/// output: str +/// Path to create the settings file +/// +/// py_run_args: PyRunArgs +/// PyRunArgs object to initialize the settings +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( model=PathBuf::from(DEFAULT_MODEL), output=PathBuf::from(DEFAULT_SETTINGS), @@ -618,7 +843,38 @@ fn gen_settings( Ok(true) } -/// calibrates the circuit settings +/// Calibrates the circuit settings +/// +/// Arguments +/// --------- +/// data: str +/// Path to the calibration data +/// +/// model: str +/// Path to the onnx file +/// +/// settings: str +/// Path to the settings file +/// +/// lookup_safety_margin: int +/// the lookup safety margin to use for calibration. if the max lookup is 2^k, then the max lookup will be 2^k * lookup_safety_margin. larger = safer but slower +/// +/// scales: list[int] +/// Optional scales to specifically try for calibration +/// +/// scale_rebase_multiplier: list[int] +/// Optional scale rebase multipliers to specifically try for calibration. This is the multiplier at which we divide to return to the input scale. +/// +/// max_logrows: int +/// Optional max logrows to use for calibration +/// +/// only_range_check_rebase: bool +/// Check ranges when rebasing +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( data = PathBuf::from(DEFAULT_CALIBRATION_FILE), model = PathBuf::from(DEFAULT_MODEL), @@ -660,7 +916,30 @@ fn calibrate_settings( Ok(true) } -/// runs the forward pass operation +/// Runs the forward pass operation to generate a witness +/// +/// Arguments +/// --------- +/// data: str +/// Path to the data file +/// +/// model: str +/// Path to the compiled model file +/// +/// output: str +/// Path to create the witness file +/// +/// vk_path: str +/// Path to the verification key +/// +/// srs_path: str +/// Path to the SRS file +/// +/// Returns +/// ------- +/// dict +/// Python object containing the witness values +/// #[pyfunction(signature = ( data=PathBuf::from(DEFAULT_DATA), model=PathBuf::from(DEFAULT_MODEL), @@ -687,7 +966,20 @@ fn gen_witness( Python::with_gil(|py| Ok(output.to_object(py))) } -/// mocks the prover +/// Mocks the prover +/// +/// Arguments +/// --------- +/// witness: str +/// Path to the witness file +/// +/// model: str +/// Path to the compiled model file +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( witness=PathBuf::from(DEFAULT_WITNESS), model=PathBuf::from(DEFAULT_MODEL), @@ -700,7 +992,23 @@ fn mock(witness: PathBuf, model: PathBuf) -> PyResult { Ok(true) } -/// mocks the aggregate prover +/// Mocks the aggregate prover +/// +/// Arguments +/// --------- +/// aggregation_snarks: list[str] +/// List of paths to the relevant proof files +/// +/// logrows: int +/// Number of logrows to use for the aggregation circuit +/// +/// split_proofs: bool +/// Indicates whether the accumulated are segments of a larger proof +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( aggregation_snarks=vec![PathBuf::from(DEFAULT_PROOF)], logrows=DEFAULT_AGGREGATED_LOGROWS.parse().unwrap(), @@ -719,7 +1027,32 @@ fn mock_aggregate( Ok(true) } -/// runs the prover on a set of inputs +/// Runs the setup process +/// +/// Arguments +/// --------- +/// model: str +/// Path to the compiled model file +/// +/// vk_path: str +/// Path to create the verification key file +/// +/// pk_path: str +/// Path to create the proving key file +/// +/// srs_path: str +/// Path to the SRS file +/// +/// witness_path: str +/// Path to the witness file +/// +/// disable_selector_compression: bool +/// Whether to compress the selectors or not +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( model=PathBuf::from(DEFAULT_MODEL), vk_path=PathBuf::from(DEFAULT_VK), @@ -752,7 +1085,32 @@ fn setup( Ok(true) } -/// runs the prover on a set of inputs +/// Runs the prover on a set of inputs +/// +/// Arguments +/// --------- +/// witness: str +/// Path to the witness file +/// +/// model: str +/// Path to the compiled model file +/// +/// pk_path: str +/// Path to the proving key file +/// +/// proof_path: str +/// Path to create the proof file +/// +/// proof_type: str +/// Accepts `single`, `for-aggr` +/// +/// srs_path: str +/// Path to the SRS file +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( witness=PathBuf::from(DEFAULT_WITNESS), model=PathBuf::from(DEFAULT_MODEL), @@ -786,7 +1144,29 @@ fn prove( Python::with_gil(|py| Ok(snark.to_object(py))) } -/// verifies a given proof +/// Verifies a given proof +/// +/// Arguments +/// --------- +/// proof_path: str +/// Path to create the proof file +/// +/// settings_path: str +/// Path to the settings file +/// +/// vk_path: str +/// Path to the verification key file +/// +/// srs_path: str +/// Path to the SRS file +/// +/// non_reduced_srs: bool +/// Whether to reduce the number of SRS logrows to the number of instances rather than the number of logrows used for proofs (only works if the srs were generated in the same ceremony) +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( proof_path=PathBuf::from(DEFAULT_PROOF), settings_path=PathBuf::from(DEFAULT_SETTINGS), @@ -816,6 +1196,38 @@ fn verify( Ok(true) } +/// Runs the setup process for an aggregate setup +/// +/// Arguments +/// --------- +/// sample_snarks: list[str] +/// List of paths to the various proofs +/// +/// vk_path: str +/// Path to create the aggregated VK +/// +/// pk_path: str +/// Path to create the aggregated PK +/// +/// logrows: int +/// Number of logrows to use +/// +/// split_proofs: bool +/// Whether the accumulated are segments of a larger proof +/// +/// srs_path: str +/// Path to the SRS file +/// +/// disable_selector_compression: bool +/// Whether to compress selectors +/// +/// commitment: str +/// Accepts `kzg`, `ipa` +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( sample_snarks=vec![PathBuf::from(DEFAULT_PROOF)], vk_path=PathBuf::from(DEFAULT_VK_AGGREGATED), @@ -854,6 +1266,23 @@ fn setup_aggregate( Ok(true) } +/// Compiles the circuit for use in other steps +/// +/// Arguments +/// --------- +/// model: str +/// Path to the onnx model file +/// +/// compiled_circuit: str +/// Path to output the compiled circuit +/// +/// settings_path: str +/// Path to the settings files +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( model=PathBuf::from(DEFAULT_MODEL), compiled_circuit=PathBuf::from(DEFAULT_COMPILED_CIRCUIT), @@ -872,7 +1301,41 @@ fn compile_circuit( Ok(true) } -/// creates an aggregated proof +/// Creates an aggregated proof +/// +/// Arguments +/// --------- +/// aggregation_snarks: list[str] +/// List of paths to the various proofs +/// +/// proof_path: str +/// Path to output the aggregated proof +/// +/// vk_path: str +/// Path to the VK file +/// +/// transcript: +/// Proof transcript type to be used. `evm` used by default. `poseidon` is also supported +/// +/// logrows: +/// Logrows used for aggregation circuit +/// +/// check_mode: str +/// Run sanity checks during calculations. Accepts `safe` or `unsafe` +/// +/// split-proofs: bool +/// Whether the accumulated proofs are segments of a larger circuit +/// +/// srs_path: str +/// Path to the SRS used +/// +/// commitment: str +/// Accepts "kzg" or "ipa" +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( aggregation_snarks=vec![PathBuf::from(DEFAULT_PROOF)], proof_path=PathBuf::from(DEFAULT_PROOF_AGGREGATED), @@ -915,7 +1378,32 @@ fn aggregate( Ok(true) } -/// verifies and aggregate proof +/// Verifies and aggregate proof +/// +/// Arguments +/// --------- +/// proof_path: str +/// The path to the proof file +/// +/// vk_path: str +/// The path to the verification key file +/// +/// logrows: int +/// logrows used for aggregation circuit +/// +/// commitment: str +/// Accepts "kzg" or "ipa" +/// +/// reduced_srs: bool +/// Whether to reduce the number of SRS logrows to the number of instances rather than the number of logrows used for proofs (only works if the srs were generated in the same ceremony) +/// +/// srs_path: str +/// The path to the SRS file +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( proof_path=PathBuf::from(DEFAULT_PROOF_AGGREGATED), vk_path=PathBuf::from(DEFAULT_VK), @@ -948,7 +1436,32 @@ fn verify_aggr( Ok(true) } -/// creates an EVM compatible verifier, you will need solc installed in your environment to run this +/// Creates an EVM compatible verifier, you will need solc installed in your environment to run this +/// +/// Arguments +/// --------- +/// vk_path: str +/// The path to the verification key file +/// +/// settings_path: str +/// The path to the settings file +/// +/// sol_code_path: str +/// The path to the create the solidity verifier +/// +/// abi_path: str +/// The path to create the ABI for the solidity verifier +/// +/// srs_path: str +/// The path to the SRS file +/// +/// render_vk_separately: bool +/// Whether the verifier key should be rendered as a separate contract. We recommend disabling selector compression if this is enabled. To save the verifier key as a separate contract, set this to true and then call the create-evm-vk command +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( vk_path=PathBuf::from(DEFAULT_VK), settings_path=PathBuf::from(DEFAULT_SETTINGS), @@ -981,7 +1494,26 @@ fn create_evm_verifier( Ok(true) } -// creates an EVM compatible data attestation verifier, you will need solc installed in your environment to run this +/// Creates an EVM compatible data attestation verifier, you will need solc installed in your environment to run this +/// +/// Arguments +/// --------- +/// input_data: str +/// The path to the .json data file, which should contain the necessary calldata and account addresses needed to read from all the on-chain view functions that return the data that the network ingests as inputs +/// +/// settings_path: str +/// The path to the settings file +/// +/// sol_code_path: str +/// The path to the create the solidity verifier +/// +/// abi_path: str +/// The path to create the ABI for the solidity verifier +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( input_data=PathBuf::from(DEFAULT_DATA), settings_path=PathBuf::from(DEFAULT_SETTINGS), @@ -1003,6 +1535,32 @@ fn create_evm_data_attestation( Ok(true) } +/// Setup test evm witness +/// +/// Arguments +/// --------- +/// data_path: str +/// The path to the .json data file, which should include both the network input (possibly private) and the network output (public input to the proof) +/// +/// compiled_circuit_path: str +/// The path to the compiled model file (generated using the compile-circuit command) +/// +/// test_data: str +/// For testing purposes only. The optional path to the .json data file that will be generated that contains the OnChain data storage information derived from the file information in the data .json file. Should include both the network input (possibly private) and the network output (public input to the proof) +/// +/// input_sources: str +/// Where the input data comes from +/// +/// output_source: str +/// Where the output data comes from +/// +/// rpc_url: str +/// RPC URL for an EVM compatible node, if None, uses Anvil as a local RPC node +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( data_path, compiled_circuit_path, @@ -1037,6 +1595,7 @@ fn setup_test_evm_witness( Ok(true) } +/// deploys the solidity verifier #[pyfunction(signature = ( addr_path, sol_code_path=PathBuf::from(DEFAULT_SOL_CODE), @@ -1069,6 +1628,7 @@ fn deploy_evm( Ok(true) } +/// deploys the solidity vk verifier #[pyfunction(signature = ( addr_path, sol_code_path=PathBuf::from(DEFAULT_VK_SOL), @@ -1101,6 +1661,7 @@ fn deploy_vk_evm( Ok(true) } +/// deploys the solidity da verifier #[pyfunction(signature = ( addr_path, input_data, @@ -1138,6 +1699,27 @@ fn deploy_da_evm( Ok(true) } /// verifies an evm compatible proof, you will need solc installed in your environment to run this +/// +/// Arguments +/// --------- +/// addr_verifier: str +/// The path to verifier contract's address +/// +/// proof_path: str +/// The path to the proof file (generated using the prove command) +/// +/// rpc_url: str +/// RPC URL for an Ethereum node, if None will use Anvil but WON'T persist state +/// +/// addr_da: str +/// does the verifier use data attestation ? +/// +/// addr_vk: str +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( addr_verifier, proof_path=PathBuf::from(DEFAULT_PROOF), @@ -1183,7 +1765,35 @@ fn verify_evm( Ok(true) } -/// creates an evm compatible aggregate verifier, you will need solc installed in your environment to run this +/// Creates an evm compatible aggregate verifier, you will need solc installed in your environment to run this +/// +/// Arguments +/// --------- +/// aggregation_settings: str +/// path to the settings file +/// +/// vk_path: str +/// The path to load the desired verification key file +/// +/// sol_code_path: str +/// The path to the Solidity code +/// +/// abi_path: str +/// The path to output the Solidity verifier ABI +/// +/// logrows: int +/// Number of logrows used during aggregated setup +/// +/// srs_path: str +/// The path to the SRS file +/// +/// render_vk_separately: bool +/// Whether the verifier key should be rendered as a separate contract. We recommend disabling selector compression if this is enabled. To save the verifier key as a separate contract, set this to true and then call the create-evm-vk command +/// +/// Returns +/// ------- +/// bool +/// #[pyfunction(signature = ( aggregation_settings=vec![PathBuf::from(DEFAULT_PROOF)], vk_path=PathBuf::from(DEFAULT_VK_AGGREGATED),