{"id":26542989,"url":"https://github.com/iluxonchik/zklocus","last_synced_at":"2025-07-30T07:04:26.681Z","repository":{"id":196915046,"uuid":"664822571","full_name":"iluxonchik/zkLocus","owner":"iluxonchik","description":"zkLocus is an application, a framework, and protocol that enables private and programmable geolocation sharing both off-chain and on-chain. Natively implemented on the Mina Protocol using the O1JS framework, zkLocus turns geolocation into a Real-World-Asset (RWA). zkLocus's DeFi ecosystem is powered by its native $ZKL token.","archived":false,"fork":false,"pushed_at":"2024-06-06T17:24:47.000Z","size":1822,"stargazers_count":43,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-07T20:04:42.364Z","etag":null,"topics":["blockchain","mina","mina-protocol","mina-zkapp","privacy","web","web3","zk","zk-snarks","zksnarks"],"latest_commit_sha":null,"homepage":"https://zklocus.dev","language":"TypeScript","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/iluxonchik.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-10T20:36:33.000Z","updated_at":"2025-02-24T02:18:46.000Z","dependencies_parsed_at":"2023-11-12T01:28:22.244Z","dependency_job_id":"3b01fa46-60d5-456e-b8b9-078d192edcc0","html_url":"https://github.com/iluxonchik/zkLocus","commit_stats":null,"previous_names":["iluxonchik/zklocus"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/iluxonchik/zkLocus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluxonchik%2FzkLocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluxonchik%2FzkLocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluxonchik%2FzkLocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluxonchik%2FzkLocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iluxonchik","download_url":"https://codeload.github.com/iluxonchik/zkLocus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluxonchik%2FzkLocus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267827337,"owners_count":24150345,"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","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["blockchain","mina","mina-protocol","mina-zkapp","privacy","web","web3","zk","zk-snarks","zksnarks"],"created_at":"2025-03-22T02:19:47.774Z","updated_at":"2025-07-30T07:04:26.636Z","avatar_url":"https://github.com/iluxonchik.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zkLocus 🌍🔒\n\n![zkLocus Logo](https://raw.githubusercontent.com/iluxonchik/blog/main/public/assets/blog/zklocus/zklocus-geolocation-for-web3.png)\n\n[![NPM Version](https://img.shields.io/npm/v/zklocus.svg)](https://www.npmjs.com/package/zklocus)\n[![Build Status](https://img.shields.io/travis/zkLocus/zklocus.svg)](https://travis-ci.org/zkLocus/zklocus)\n[![License](https://img.shields.io/npm/l/zklocus.svg)](https://github.com/iluxonchik/zkLocus/blob/main/contracts/LICENSE)\n\nzkLocus is an application, a framework, and protocol that enables private and programmable geolocation sharing both off-chain and on-chain. Natively implemented on the Mina Protocol using the O1JS framework, zkLocus turns geolocation into a Real-World-Asset (RWA). 🌍💻\n\n\n\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Generating Geolocation Proofs](#generating-geolocation-proofs)\n    - [Creating ZKGeoPoint Instances](#creating-zkgeopoint-instances)\n    - [Generating Proofs for Polygons](#generating-proofs-for-polygons)\n    - [Generating Proofs for Multiple Polygons](#generating-proofs-for-multiple-polygons)\n  - [Verifying Geolocation Proofs](#verifying-geolocation-proofs)\n  - [Attaching Metadata to Geolocation Proofs](#attaching-metadata-to-geolocation-proofs)\n  - [Combining Geolocation Proofs](#combining-geolocation-proofs)\n    - [AND Combination](#and-combination)\n    - [OR Combination](#or-combination)\n  - [Authenticating Geolocation with Integration Oracle](#authenticating-geolocation-with-integration-oracle)\n  - [Generating Exact Geolocation Proofs](#generating-exact-geolocation-proofs)\n  - [Combining Point-in-Polygon Proofs](#combining-point-in-polygon-proofs)\n- [API Reference](#api-reference)\n  - [ZKGeoPoint](#zkgeopoint)\n  - [ZKThreePointPolygon](#zkthreepointpolygon)\n  - [ZKGeoPointInPolygonProof](#zkgeopointinpolygonproof)\n  - [ZKGeoPointInOrOutOfPolygonCircuitProof](#zkgeopointinoroutofpolygoncircuitproof)\n  - [ZKExactGeoPointCircuitProof](#zkexactgeopointcircuitproof)\n  - [ZKExactGeolocationMetadataCircuitProof](#zkexactgeolocationmetadatacircuitproof)\n- [Testing](#testing)\n- [Building](#building)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nzkLocus leverages recursive zkSNARKs and Mina blockchain to enable a secure, private, and verifiable protocol for sharing geolocation data. It allows users to prove their presence within specific geographical regions without revealing their exact coordinates. With zkLocus, you can generate proofs for various geolocation scenarios, attach metadata to proofs, and combine and compress proofs. 🌐🔐\n\n## zkLocus: Authenticated Private Geolocation Off \u0026 On-Chain\n\nzkLocus is a Zero-Knowledge, on-chain, cross-chain, and off-chain protocol, enabling authenticated, private and verifiable geolocation sharing. It allows users to authenticate their presence in specific geographical areas without revealing exact coordinates. For example, a user can prove they are within the European Union without disclosing their precise location. Additionally, zkLocus provides the flexibility for users to share precise coordinates when desired, with the option for semi-private sharing with selected entities. It's also possible to veriably share exact geolocation on-chain, thus turning it into a Real-World-Asset(RWA). In Ethereum terms, it allows you to create a non-fungible token (NFT) / ERC-720 for geolocation data.\n\nBy bringing geolocation data onto the blockchain, zkLocus enables decentralized, verifiable, and transparent geolocation sharing. It offers native bridging capabilities, allowing for easy integration with any other blockchain such as Ethereum, Cardano and Polygon Miden, either through bridging or by direcly verifying zkLocus zkSNARK proofs on the target blockchain. Moreover, zkLocus supports native rollup functionality and infinite proof compression, thanks to its architecture based on recursive zkSNARKs.\n\n## zkSafeZones: Blockchain \u0026 Zero-Knowledge for Civilian Protection in Conflict Zones\n\nzkSafeZones is a solution that leverages zkLocus, the Mina Protocol, and recursive zkSNARKs to establish a system for safeguarding civilians in conflict areas. It introduces an economic model centered around the $ZKL token, incentivizing the submission of geolocation data and legal evidence. This fosters a self-sustainable, decentralized legal system for protecting civilians and ensuring compliance with international law.\n\nBy enabling private, verifiable geolocation sharing, zkSafeZones aims to enhance civilian protection and adherence to the International Humanitarian Law (IHL) principles, such as the principles of distinction, proportionality, and necessity.\n\n## More Information 💡\n\nYou can find more information about zkLocus and zkSafeZones in the following resources:\n\n- [📝 zkLocus Whitepaper](https://zklocus.dev/whitepaper)\n- [⛑️ zkSafeZones Whitepaper](https://zklocus.dev/zkSafeZones)\n- [📍 zkLocus Homepage](https://zklocus.dev/)\n\n## Installation\n\nTo install zkLocus, run the following command:\n\n```bash\nnpm install zklocus\n```\n\n## Usage\n\n### Generating Geolocation Proofs\n\nzkLocus provides a flexible and intuitive end-user API for generating geolocation proofs. This API abstracts away the Zero-Knowledge details and can be used with your JavaScript/TypeScript code. You can create proofs for a single polygon or multiple polygons, attach metadata to proofs, and combine proofs using logical operators.\n\n#### Creating ZKGeoPoint Instances\n\nTo generate a geolocation proof, you first need to create a `ZKGeoPoint` instance representing the geographical point:\n\n```typescript\nimport { ZKGeoPoint } from 'zklocus';\n\nconst latitude = 40.7128;\nconst longitude = -74.0060;\nconst zkGeoPoint = new ZKGeoPoint(latitude, longitude);\n```\n\n#### Generating Proofs for Polygons\n\nOnce you have a `ZKGeoPoint` instance, you can generate a proof for a specific polygon using the `inPolygon()` method:\n\n```typescript\nimport { ZKThreePointPolygon } from 'zklocus';\n\nconst polygon = new ZKThreePointPolygon(\n  { latitude: 40.7128, longitude: -74.0060 },\n  { latitude: 40.7129, longitude: -74.0061 },\n  { latitude: 40.7130, longitude: -74.0062 }\n);\n\nconst proof = await zkGeoPoint.Prove.inPolygon(polygon);\n```\n\n#### Generating Proofs for Multiple Polygons\n\nYou can also generate proofs for multiple polygons simultaneously using the `inPolygons()` method:\n\n```typescript\nconst polygons = [\n  new ZKThreePointPolygon(...),\n  new ZKThreePointPolygon(...),\n  new ZKThreePointPolygon(...)\n];\n\nconst proofs = await zkGeoPoint.Prove.inPolygons(polygons);\n```\n\n### Verifying Geolocation Proofs\n\nTo verify a geolocation proof, you can use the `verify()` method:\n\n```typescript\nproof.verify();\n```\n\nThis method will throw an error if the proof is invalid.\n\n### Attaching Metadata to Geolocation Proofs\n\nzkLocus allows you to attach arbitrary metadata to geolocation proofs. You can use the `attachMetadata()` method to associate metadata with a proof:\n\n```typescript\nconst metadata = \"Hello, world!\";\nconst proofWithMetadata = await zkGeoPoint.Prove.attachMetadata(metadata);\n```\n\nThe attached metadata can be of any size and type, providing flexibility for various use cases.\n\n### Combining Geolocation Proofs\n\nzkLocus enables you to combine multiple geolocation proofs using logical operators such as `AND` and `OR`. This feature allows you to create more complex proofs that represent the combination of multiple conditions.\n\n#### AND Combination\n\nTo combine proofs using the `AND` operator, you can use the `AND()` method:\n\n```typescript\nconst combinedProof = await proof1.AND(proof2);\n```\n\nThe resulting proof will be valid only if both `proof1` and `proof2` are valid.\n\n#### OR Combination\n\nTo combine proofs using the `OR` operator, you can use the `OR()` method:\n\n```typescript\nconst combinedProof = await proof1.OR(proof2);\n```\n\nThe resulting proof will be valid if either `proof1` or `proof2` is valid.\n\n### Authenticating Geolocation with Integration Oracle\n\nzkLocus provides an [Integration Oracle](https://github.com/zkLocus/integration-oracle) that allows you to authenticate geolocation data using external sources. You can use the `authenticateFromIntegrationOracle()` method to create an authenticated geolocation proof:\n\n```typescript\nimport { ZKPublicKey, ZKSignature } from 'zklocus';\n\nconst publicKey = new ZKPublicKey(...);\nconst signature = new ZKSignature(...);\n\nconst authenticatedProof = await zkGeoPoint.Prove.authenticateFromIntegrationOracle(publicKey, signature);\n```\n\n### Generating Exact Geolocation Proofs\n\nIn addition to generating proofs for polygons, zkLocus allows you to create proofs for exact geographical points. You can use the `exactGeoPoint()` method to generate an exact geolocation proof:\n\n```typescript\nconst exactProof = await zkGeoPoint.Prove.exactGeoPoint();\n```\n\n### Combining Point-in-Polygon Proofs\n\nzkLocus provides the `combinePointInPolygonProofs()` method to combine multiple point-in-polygon proofs into a single proof:\n\n```typescript\nconst combinedProof = await zkGeoPoint.Prove.combinePointInPolygonProofs();\n```\n\nThis method combines the proofs that the `ZKGeoPoint` is inside and outside of different polygons into a single proof.\n\n## API Reference\n\n### ZKGeoPoint\n\nRepresents a geographical point with latitude and longitude coordinates.\n\n#### Constructor\n\n```typescript\nnew ZKGeoPoint(latitude: number | ZKLatitude, longitude: number | ZKLongitude)\n```\n\n#### Methods\n\n- `Prove.inPolygon(polygon: ZKThreePointPolygon): Promise\u003cZKGeoPointInPolygonProof\u003e`\n- `Prove.inPolygons(polygons: ZKThreePointPolygon[]): Promise\u003cZKGeoPointInPolygonProof[]\u003e`\n- `Prove.combineProofs(proofs: ZKGeoPointInPolygonProof[]): Promise\u003cZKGeoPointInPolygonProof\u003e`\n- `Prove.combinePointInPolygonProofs(): Promise\u003cZKGeoPointInOrOutOfPolygonCircuitProof\u003e`\n- `Prove.authenticateFromIntegrationOracle(publicKey: ZKPublicKey, signature: ZKSignature): Promise\u003cZKGeoPointProviderCircuitProof\u003e`\n- `Prove.exactGeoPoint(): Promise\u003cZKExactGeoPointCircuitProof\u003e`\n- `Prove.attachMetadata(metadata: string): Promise\u003cZKExactGeolocationMetadataCircuitProof\u003e`\n\n### ZKThreePointPolygon\n\nRepresents a polygon defined by three geographical points.\n\n#### Constructor\n\n```typescript\nnew ZKThreePointPolygon(\n  vertex1: ZKGeoPoint | RawCoordinates,\n  vertex2: ZKGeoPoint | RawCoordinates,\n  vertex3: ZKGeoPoint | RawCoordinates\n)\n```\n\n### ZKGeoPointInPolygonProof\n\nRepresents a proof that a ZKGeoPoint is inside a ZKThreePointPolygon.\n\n#### Methods\n\n- `verify(): void`\n- `AND(other: ZKGeoPointInPolygonProof): Promise\u003cZKGeoPointInPolygonProof\u003e`\n- `OR(other: ZKGeoPointInPolygonProof): Promise\u003cZKGeoPointInPolygonProof\u003e`\n\n### ZKGeoPointInOrOutOfPolygonCircuitProof\n\nRepresents a proof that a ZKGeoPoint is inside or outside of a polygon.\n\n#### Methods\n\n- `verify(): void`\n\n### ZKExactGeoPointCircuitProof\n\nRepresents a proof for an exact geographical point (GeoPoint) in a zero-knowledge circuit.\n\n#### Methods\n\n- `verify(): void`\n\n### ZKExactGeolocationMetadataCircuitProof\n\nRepresents a proof of an exact GeoPoint with associated metadata.\n\n#### Methods\n\n- `verify(): void`\n\n## $ZKL Token and DeFi Ecosystem\n\nzkLocus introduces the $ZKL token, which serves as the foundation for a DeFi ecosystem built around the zkLocus platform. The $ZKL token enables various use cases and incentives within the zkLocus ecosystem, including:\n\n- Fully Private Geolocation Sharing: Users can share their geolocation without exposing any personally identifiable information, such as their IP address or Mina address. By associating a bounty in $ZKL tokens with their geolocation proof, users can incentivize others to submit the proof on their behalf, ensuring privacy and anonymity.\n\n- Outsourcing Proof Submission: $ZKL tokens allow users to outsource the submission of their geolocation proofs to others by attaching a bounty for the submission. This eliminates the need for users to maintain their own infrastructure, making zkLocus more accessible and user-friendly.\n\n- Digital Evidence Collection: In the zkSafeZones proposal, $ZKL tokens play a crucial role in digital evidence collection. Bounties in $ZKL tokens can be associated with specific geolocation proofs, incentivizing users to collect and submit relevant evidence, even in offline scenarios.\n\nThe $ZKL token and its associated DeFi ecosystem enable a self-sustaining and decentralized economy within zkLocus, fostering participation, privacy, and accessibility.\n\n## Offline Functionality\n\nzkLocus is designed to operate seamlessly in offline environments. Users can generate geolocation proofs offline and later submit them to the blockchain when an internet connection becomes available. This offline capability ensures that zkLocus remains functional even in areas with limited or intermittent connectivity, making it suitable for a wide range of applications and scenarios. For a practical application of this consult the [⛑️ zkSafeZones Whitepaper](https://zklocus.dev/zkSafeZones).\n\n## Metadata Association\n\nzkLocus allows arbitrary metadata to be associated with geolocation proofs. This metadata can include commitments to any external data, such as documents, images, or even entire blockchains. By associating metadata with zkLocus proofs, users can create rich and context-specific geolocation attestations, enabling integration with various systems and applications.\n\n## Off-Chain and Legacy System Integration\n\nzkLocus proofs can be used off-chain and integrated with Web 2.0 and legacy systems. The `ZkProgram`s are a low-level abstraction over Zero-Knowledge circuits that enable the generation of raw zkSNARKs proofs, which can be loaded and verified in any environment. This allows zkLocus to be seamlessly integrated into existing infrastructures and applications, extending its utility beyond the blockchain ecosystem.\n\n## Cross-Chain Integration\n\nzkLocus is natively implemented on Mina Protocol blockchain, but can be integrated into any solution or blockchain, either through bridging or by using the raw zkSNARKs. We are currently working on porting zkLocus to expand its reach and interoperability. This cross-environment integration will enable zkLocus to be direcly used across a diverse range of decentralized applications and ecosystems.\n\n## Testing\n\nzkLocus comes with a comprehensive test suite to ensure the reliability and correctness of the library. To run the tests, use the following command:\n\n```bash\nnpm run test\n```\n\nThe test suite covers various scenarios, including generating proofs, verifying proofs, attaching metadata, combining proofs, and more.\n\n## Building\n\nTo build the zkLocus project, run the following command:\n\n```bash\nnpm run build\n```\n\nThis command will compile the TypeScript source code into JavaScript and generate the necessary build artifacts.\n\n## Contributing\n\nWe welcome contributions to zkLocus! If you'd like to contribute, please follow these steps:\n\n1. Fork the repository\n2. Create a new branch for your feature or bug fix\n3. Make your changes and commit them with descriptive messages\n4. Push your changes to your forked repository\n5. Submit a pull request to the main zkLocus repository\n\nPlease ensure that your code follows the project's coding style and conventions. Also, make sure to write tests for your changes and ensure that all existing tests pass.\n\n## License\n\nzkLocus is released under the [Apache License 2.0](https://github.com/iluxonchik/zkLocus/blob/main/contracts/LICENSE)\n\n## Contact\n\nFor any inquiries or collaboration opportunities, please reach out to us at:\n\n- [📧 contact@zklocus.dev](mailto:contact@zklocus.dev)\n- [🐤 Twitter/X](https://x.com/zkLocus)\n- [📍 Homepage](https://zklocus.dev)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filuxonchik%2Fzklocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filuxonchik%2Fzklocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filuxonchik%2Fzklocus/lists"}