{"id":25935571,"url":"https://github.com/hicsail/oracles","last_synced_at":"2025-11-30T23:11:09.634Z","repository":{"id":48523079,"uuid":"332047545","full_name":"hicsail/ORACLES","owner":"hicsail","description":"Useful zero-knowledge (ZK) problems constructed from real world scenarios. ","archived":false,"fork":false,"pushed_at":"2021-07-30T01:52:11.000Z","size":147,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-24T10:53:03.924Z","etag":null,"topics":["cryptography","zero-knowledge-proofs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hicsail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-22T19:50:42.000Z","updated_at":"2024-04-24T10:53:03.925Z","dependencies_parsed_at":"2022-08-29T13:31:19.791Z","dependency_job_id":null,"html_url":"https://github.com/hicsail/ORACLES","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hicsail%2FORACLES","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hicsail%2FORACLES/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hicsail%2FORACLES/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hicsail%2FORACLES/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hicsail","download_url":"https://codeload.github.com/hicsail/ORACLES/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241768377,"owners_count":20017117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","zero-knowledge-proofs"],"created_at":"2025-03-04T01:38:33.327Z","updated_at":"2025-11-30T23:11:09.582Z","avatar_url":"https://github.com/hicsail.png","language":"Python","readme":"# ORACLES\n\nThis repository contains code for the SIEVE/ORACLES TA1 project, whose goal is to create verifiable computations for legally, socially, or commercially relevant scenarios by constructing intermediate representations (IRs) that can be proved in zero-knowledge. \n\nThe code executes computations and outputs them in the zkInterface intermediate representation format. This zkInterface output can then be used by a third party to verify that the computation was executed correctly, but without revealing the input data to the third party. We assert that the input data has not been modified maliciously by hashing the input data and matching the hash to a known public hash of the input data. We assume that the publicly known hash was computed correctly. The correctness of the hash is beyond the scope of these proofs.\n\n## Workflow\nTo construct a verifiable computation, the prover runs the code in this repository using their private data as input.\n\nThe code outputs a `computation.zkif` zkInterface file. This zkInterface file can be verified as is or can be converted into the SIEVE IR format.\n\nThe `computation.zkif` file can be converted into `.sieve` SIEVE IR files using the [SIEVE IR Toolbox](https://github.mit.edu/sieve-all/zkinterface-sieve) on the MIT GitHub. \n\nFinally, we prove the constructed zk-SNARKs are valid. Since both zkInterface and SIEVE IR are intermediate representations, we can prove the constructed zk-SNARKs using various backends. \n\nNote that the workflow in this README simply uses zkInterface and SIEVE IR utilities to verify the proofs. The workflow does not create a true zk-SNARK and is therefore not secure. To verify these proofs using a real backend, run the scripts with the appropriate `PYSNARK_BACKEND` environment variable, update the expected hash values according to the new prime field, and follow the backend's instructions to construct and verify a secure zk-SNARK.\n\n## Installing\n\nFirst, install Python 3 and Rust.\n\nNext, install the PySNARK library along with its requirements:\n```\npip3 install git+https://github.com/gxavier38/pysnark.git@master\npip3 install flatbuffers\n```\n\nThen, clone the ORACLES repo:\n```\ngit clone https://github.com/hicsail/ORACLES.git\ncd ORACLES/src/\n```\n\n## Running\n\nFirst, set up environment variables for PySNARK:\n```\nexport PYSNARK_BACKEND=zkinterface\n```\n\nThen, run the appropriate Python script. For example, to run the GPA script:\n```\ncd src \npython3 gpa.py\n```\n\n## Verifying\n\n### zkInterface\n\nTo verify using the zkInterface toolkit, first download and install the zkInterface toolkit:\n```\ngit clone https://github.com/QED-it/zkinterface.git\ncargo install --path zkinterface/rust/\n```\n\nFinally, navigate to the folder containing the `computation.zkif` file and run:\n```\nzkif validate\nzkif simulate\n```\n\n### SIEVE IR Toolbox\n\nTo verify using the SIEVE IR Toolbox, first install and download the SIEVE IR toolbox from the MIT GitHub:\n```\ngit clone git@github.mit.edu:sieve-all/zkinterface-sieve.git\ncargo install --path zkinterface-sieve/rust/\n```\n\nFinally, navigate to the folder containing the `computation.zkif` file and run:\n```\nzki_sieve zkif-to-ir\nzki_sieve validate\nzki_sieve simulate\n```\n\n## Implementing Proofs\n\nWe use the PySNARK library to convert a computation into a circuit that can be verified. The output circuit is an arithmetic circuit. Hence, our computation must consist of only arithmetic and logical operations. All inputs and variables must also be integers or booleans. Hence, we must convert all inputs into an integer representation.\n\nAll inputs must then be converted into a PySNARK data type. `PubVal`s and `PubValFxp`s are public integers and floats respectively, while `PrivVal`s and `PrivValFxp`s are their private equivalents. We turn our secret inputs into private values and let the expected outputs be public values.\n\nWe then pass the inputs into a function that executes our computation. We apply the `@snark` decorator to the function. The decorator automatically convert all integer inputs - including those in arrays - into `PubVal`s. Note that floats and contents of dictionaries are not converted. To use these data types, convert their contents into PySNARK data types manually. To make inputs private, construct `PrivVal`s out of them manually **outside the decorated function**. \n\nWithin the function, hash the input data and ensure that they match the publicly known hash. Next, execute the computation and check that the outputs match the expected outputs. Use assertion like `assert_eq()` to check that values are equal.\n\n### Implementation Notes\n\nThe circuit representing the computation is output as public knowledge. Hence, all operations in our computation should be applied to all inputs to prevent data being revealed. \n\nFor example, we can find the sum of two sets of inputs as follows:\n```\nset1 = [PrivVal(0), PrivVal(1)]\nset2 = [PrivVal(1), PrivVal(2), PrivVal(3)]\n\nsum1 = sum(set1)\nsum2 = sum(set2)\n```\nHowever, `sum1` will have an in-degree of 2, while the `sum2` gate will have an in-degree of 3. Hence, the verifier can find the number of inputs in each set.\n\nAlternatively, we can encode the second set by multiplying their value by 10. Then, we can modify the computation as follows:\n```\ninputs = [PrivVal(0), PrivVal(1), PrivVal(10), PrivVal(20), PrivVal(30)]\n\nsum1 = sum([x // 10 for x in inputs])\nsum2 = sum([x % 10 for x in inputs]])\n```\nHere, all operations are applied to all the inputs. This construction prevents the number of inputs in each set being leaked.\n\n### Other Notes\n\nDuring bitwise and comparison operations, PySNARK assumes inputs are 16 bits long by default.\nThis may cause overflow problems, especially with fixed point values where values are multiplied by `2 ** LinCombFxp.resolution` (8 by default).\nIf overflows occur, increase the number of bits as follows:\n```\nfrom pysnark import runtime\nruntime.bitlength = 20\n```\n\n## External Reading\n* [What is a zero-knowledge proof?](https://zkp.science/)\n* [R1CS](http://www.zeroknowledgeblog.com/index.php/the-pinocchio-protocol/r1cs)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhicsail%2Foracles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhicsail%2Foracles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhicsail%2Foracles/lists"}