{"id":28470546,"url":"https://github.com/magicblock-labs/ephemeral-vrf","last_synced_at":"2025-07-01T17:30:49.996Z","repository":{"id":289813093,"uuid":"947207447","full_name":"magicblock-labs/ephemeral-vrf","owner":"magicblock-labs","description":"Verifiable Random Function (VRF) implementation for Solana","archived":false,"fork":false,"pushed_at":"2025-04-25T15:35:24.000Z","size":574,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-07T09:35:33.170Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magicblock-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2025-03-12T10:20:17.000Z","updated_at":"2025-05-13T14:11:19.000Z","dependencies_parsed_at":"2025-04-25T07:34:06.760Z","dependency_job_id":"80d6396a-b5f0-45cb-aef1-ec3c83749847","html_url":"https://github.com/magicblock-labs/ephemeral-vrf","commit_stats":null,"previous_names":["magicblock-labs/ephemeral-vrf"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/magicblock-labs/ephemeral-vrf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicblock-labs%2Fephemeral-vrf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicblock-labs%2Fephemeral-vrf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicblock-labs%2Fephemeral-vrf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicblock-labs%2Fephemeral-vrf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magicblock-labs","download_url":"https://codeload.github.com/magicblock-labs/ephemeral-vrf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicblock-labs%2Fephemeral-vrf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263007042,"owners_count":23398750,"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":[],"created_at":"2025-06-07T09:31:01.217Z","updated_at":"2025-07-01T17:30:49.981Z","avatar_url":"https://github.com/magicblock-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EphemeralVrf\n\n**EphemeralVrf** is a Verifiable Random Function (VRF) implementation for Solana that provides secure, verifiable randomness for decentralized applications. \nIt uses a network of oracles to generate and verify random values on-chain.\n\n## Overview     \n\nEphemeralVrf enables dApps to request unpredictable, tamper-resistant random values that can be verified by anyone.\n\nThe implementation follows [RFC 9381](https://datatracker.ietf.org/doc/html/rfc9381), utilizing Curve25519's Ristretto group for elliptic curve operations and Schnorr-like signatures for proof verification. \n\n## API\n- [`Consts`](api/src/consts.rs) – Program constants.\n- [`Error`](api/src/error.rs) – Custom program errors.\n- [`Instruction`](api/src/instruction.rs) – Declared instructions.\n- [`SDK`](api/src/sdk.rs) – Custom program events.\n- [`State`](api/src/state) – Program state definitions.\n- [`DelegateOracleQueue`](program/src/delegate_oracle_queue.rs) – Delegate an Oracle queue to the delegation program.\n\n## Instructions\n\n- [`RequestRandomness`](program/src/request_randomness.rs) – Request a new random value.\n- [`ProvideRandomness`](program/src/provide_randomness.rs) – Provide randomness for a request.\n- [`Initialize`](program/src/initialize.rs) – Initialize the program state.\n- [`ModifyOracle`](program/src/modify_oracles.rs) – Add or modify oracle information.\n- [`InitializeOracleQueue`](program/src/initialize_oracle_queue.rs) – Initialize a new oracle queue.\n\n##  Errors\n\n- Unauthorized – The authority is not authorized to perform the operation.\n- RandomnessRequestNotFound – The requested randomness was not found.\n- InvalidProof – The provided VRF proof is invalid.\n\n## State\n\n- [`Oracle`](api/src/state/oracle.rs) – Oracle data structure.\n- [`Oracles`](api/src/state/oracles.rs) – Collection of oracles.\n- [`Queue`](api/src/state/queue.rs) – Oracle queue for randomness requests.\n\n## What is a VRF?\n\nA Verifiable Random Function (VRF) is a cryptographic primitive that maps inputs to verifiable pseudorandom outputs. The key properties of a VRF are:\n\n1. Uniqueness: For a given input and private key, there is exactly one valid output.\n2. Verifiability: Anyone with the public key can verify that an output was correctly computed from the input without learning the private key.\n3. Pseudorandomness: The output appears random to anyone who doesn't know the private key.\n\n4. In EphemeralVrf, oracles use VRFs to generate random values that can be verified on-chain, ensuring that the randomness is both unpredictable and tamper-resistant.\n\n## VRF Implementation\n\nThis repository contains an implementation of a **Verifiable Random Function (VRF)** based on **Curve25519** elliptic curve cryptography, using **HKDF** (HMAC-based Key Derivation Function) for key derivation and **SHA-512** as the hash function. The VRF is designed to allow a party to prove that they know a random value derived from a secret key, with the proof being verifiable by any third party.\n\n### Key Features\n\n- **Curve25519-based VRF**: The VRF is implemented using the **Ristretto group** of Curve25519, offering high security and efficiency.\n- **Key Generation**: The secret and public keys are derived using **HKDF**, ensuring secure key generation from an initial keypair.\n- **VRF Computation**: The VRF output is computed by hashing the input to a point and applying scalar multiplication. The proof consists of commitments and a response that is verified through a Schnorr-like signature scheme.\n- **Proof Verification**: The verification function checks two **Schnorr-like** relations, ensuring the integrity and validity of the VRF proof.\n\n### Cryptographic Primitives\n\n- **Curve25519**: The cryptographic foundation of the VRF, offering a secure elliptic curve with efficient computation and strong security guarantees.\n    - **Ristretto group**: Provides non-malleability and robustness in scalar operations.\n    - **Scalar multiplication**: Used to generate public keys and VRF outputs.\n\n- **SHA-512**: A strong hash function used throughout the protocol, including in the key derivation and challenge generation.\n\n- **HKDF**: A key derivation function that is based on **HMAC** and used for securely generating secret keys from initial entropy sources.\n\n- **Schnorr-like Signature Scheme**: Used for generating and verifying the VRF proof, ensuring that the output is verifiably bound to the input and secret key.\n\n## Approach\n\nThe VRF implementation follows the structure laid out in **RFC 9381**, consisting of the following steps:\n\n1. **Key Generation**: A key pair is derived from a given keypair using **HKDF** to generate a secret key (`sk`) and a corresponding public key (`pk`), which is a scalar multiple of the base point on Curve25519.\n\n2. **VRF Computation**:\n    - The input is hashed to a point using the `hash_to_point` function.\n    - The output of the VRF is computed by multiplying the secret key (`sk`) with the hashed point.\n    - A nonce (`k`) is derived, and commitments are computed for both the base point and the hashed point.\n    - A challenge value is generated by combining various elements (output, commitments, etc.) and hashing them. The final response (`s`) is computed using the standard Schnorr signature response formula.\n\n3. **VRF Proof Verification**:\n    - The verifier recomputes the challenge and checks two **Schnorr-like** relations:\n        - **Base point check**: `s * G == commitment_base + c * pk`\n        - **Hashed point check**: `s * h == commitment_hash + c * output`\n    - If both checks pass, the proof is valid.\n\n## Soundness\n\nThe security of the VRF relies on the hardness of the **Discrete Logarithm Problem (DLP)** in elliptic curve cryptography. The implementation ensures that:\n\n1. **Correctness**: The VRF proof is guaranteed to be correct if the two Schnorr-style checks hold.\n2. **Unforgeability**: An adversary cannot generate a valid proof without knowledge of the secret key.\n3. **Binding**: The output is bound to the input, ensuring that the same input always produces the same output and proof.\n4. **Non-malleability**: The proof cannot be altered or manipulated without invalidating the verification.\n\n## Warning\n\nThe code is not audited and should not be used in production environments without thorough testing and security analysis.\n\n## Get started\n\nCompile your program:\n```sh\ncargo build-sbf\n```\n\nRun unit and integration tests:\n```sh\ncargo test-sbf --features test-sbf\n```\n\nRun the oracle service:\n```sh\nRUST_LOG=info cargo run --bin vrf-oracle \n```\n\n## Oracle CLI\n\nCLI for managing oracles. See all available commands with:\n\n```bash\ncargo run --bin vrf-cli -- --help\n```\n\n## Example Usage\n\nSee the [integration tests](program/tests/integration/use-randomness/programs/use-randomness/src/lib.rs) for example usage of the program.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicblock-labs%2Fephemeral-vrf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagicblock-labs%2Fephemeral-vrf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicblock-labs%2Fephemeral-vrf/lists"}