{"id":17946508,"url":"https://github.com/erhant/aligned-vnns","last_synced_at":"2025-04-30T14:44:06.956Z","repository":{"id":259981547,"uuid":"878134219","full_name":"erhant/aligned-vnns","owner":"erhant","description":"Verifiable nearest-neighbor search with Aligned Layer \u0026 SP1.","archived":false,"fork":false,"pushed_at":"2025-03-05T20:58:01.000Z","size":1889,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T17:11:09.445Z","etag":null,"topics":["aligned","rust","succinct","zero-knowledge"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erhant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-24T20:54:05.000Z","updated_at":"2025-03-05T20:58:04.000Z","dependencies_parsed_at":"2025-02-09T03:30:21.370Z","dependency_job_id":"3a4d8ae4-c750-409c-9c10-2c03f280932c","html_url":"https://github.com/erhant/aligned-vnns","commit_stats":null,"previous_names":["erhant/aligned-vnns"],"tags_count":0,"template":false,"template_full_name":"succinctlabs/sp1-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erhant%2Faligned-vnns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erhant%2Faligned-vnns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erhant%2Faligned-vnns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erhant%2Faligned-vnns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erhant","download_url":"https://codeload.github.com/erhant/aligned-vnns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251723251,"owners_count":21633113,"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":["aligned","rust","succinct","zero-knowledge"],"created_at":"2024-10-29T07:05:58.131Z","updated_at":"2025-04-30T14:44:06.946Z","avatar_url":"https://github.com/erhant.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Verifiable Nearest Neighbor Search\n\nA **verifiable nearest-neighbor search** program, powered by [SP1](https://github.com/succinctlabs/sp1).\n\nThis project was built for [Aligned Builders Hackathon](https://devfolio.co/alignedhackathon/):\n\n- [Project Link](https://devfolio.co/projects/verifiable-similarity-27b9)\n- [Presentation](./vnns-presentation.pdf)\n\nIt has [won the 3rd place](https://x.com/alignedlayer/status/1862163883567559092)!\n\nThe requested information as per the [judging criteria](https://blog.alignedlayer.com/aligned-builders-hackathon-prizes-and-judging-criteria/) has been given within the project link above.\n\n## Setup\n\n### Installation\n\nYou need the following:\n\n- [Rust](https://rustup.rs/) for everything\n- [SP1](https://docs.succinct.xyz/getting-started/install.html) for zkVM\n- [Ollama](https://ollama.com/) for embeddings (optional)\n- [Aligned SDK](https://docs.alignedlayer.com/introduction/1_try_aligned#quickstart) for proof verification\n\n### Keystore\n\nYou can create a new wallet \u0026 store it directly in a random file with:\n\n```sh\nPRIV_KEY=$(cast wallet new | grep \"Private key\" | cut -d ' ' -f 3)\n\n# will prompt for a password, can be left empty\ncast wallet import --private-key $PRIV_KEY -k ./secrets/ $RANDOM.json\n```\n\nIt will prompt for a password, and then output the keystore under [`secrets`](./secrets/) folder.\n\nYou can view the respective address of a keystore file with:\n\n```sh\n# will prompt for the password\ncast wallet address --keystore ./secrets/wallet.json\n```\n\n### Aligned SDK\n\nFirst, deposit some funds to Aligned layer (skip this if you already have done so):\n\n```sh\n./aligned deposit ./path/to/keystore.json\n```\n\nThis will print a transaction hash, which can be viewed at `https://holesky.etherscan.io/tx/\u003chash-here\u003e`.\n\nYou can check your balance with:\n\n```sh\n./aligned balance ./path/to/keystore.json\n```\n\n### Embeddings\n\n\u003e [!WARNING]\n\u003e\n\u003e You need to have Ollama running on `localhost:11434` (default) to run the commands in this section.\n\nThe repository comes with existing embeddings under the [`data`](./data/) folder, within the files with `.index.json` extension. For this project, each data has the following type:\n\n```ts\n{\n  name: string;\n  description: string;\n}\n```\n\nYou can create your own embeddings as follows:\n\n```sh\ncargo run --bin vnns-embedder index -p ./path/to/data.json\n# will output ./path/to/data.index.json\n```\n\n### Generate Query Vector\n\nTo generate a query vector to be used within a proof, use the following command:\n\n```sh\ncargo run --bin vnns-embedder query -p ./path/to/data.json -t \"your text to be converted here\"\n# will output ./path/to/data.query.json\n```\n\nThis saves the vector itself within the JSON file, which the prover reads from disk.\n\n## Usage\n\n### Build\n\nTo build the VNNS program, run the following command:\n\n```sh\ncd program\ncargo prove build --elf-name riscv32im-succinct-vnns-elf\n```\n\nTo build the aggregator program:\n\n```sh\ncd aggregator\ncargo prove build --elf-name riscv32im-succinct-aggregator-elf\n```\n\n### Execute\n\nTo run the program without generating a proof:\n\n```sh\nRUST_LOG=info cargo run --bin vnns-script --release -- --execute --path ./data/foods-small.json\n```\n\nThis will execute the program and display the output.\n\n### Prove\n\nTo generate a core proof for your program:\n\n```sh\nRUST_LOG=info cargo run --bin vnns-script --release -- --prove --path ./data/foods-small.json\n```\n\nThis will generate many proofs (based on file size \u0026 batch size) and store them under the same directory as given in `path`. To see which text the result belongs to, copy the `Output Commitment` on the console, and look-up the item within the vector index that has the same hash with that commitment.\n\n\u003e [!TIP]\n\u003e\n\u003e You can configure the batch size with `--batch-size \u003cnumber\u003e` argument, default is 4.\n\u003e The batch size should be small especially if the vector is large (1000s of elements) because they are all of type `f32` and will consume a lot of resources within the zkVM.\n\n\u003e [!TIP]\n\u003e\n\u003e If `--aggregate` option is passed, it will aggregate and store the final proof as well with the extension `.agg.proof` and `.agg.pub`.\n\n### Submit\n\nConsider proofs generated for some data `./data.json`. You can submit all batches of proofs to Aligned Layer with:\n\n```sh\n./aligned.sh submit ./path/to/keystore.json ./data.json\n```\n\nTo send the aggregated proof only, you can use:\n\n```sh\n./aligned.sh submit-agg ./path/to/keystore.json ./data.json\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e For each proof, it will ask for your keystore password.\n\n## License\n\nThe project is MIT licensed as per SP1 project template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferhant%2Faligned-vnns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferhant%2Faligned-vnns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferhant%2Faligned-vnns/lists"}