# VRF

<figure><img src="/files/KNWc4Uj6ChXCoZfx9p5d" alt=""><figcaption></figcaption></figure>

## How Paintswap VRF Works

Paintswap VRF (Verifiable Random Function) provides secure, provably fair random numbers for smart contracts on the Sonic blockchain. Unlike traditional RNG services, Paintswap VRF uses cryptography and Web3 using Sonic's distributed ledger to prove that the output was determined by the inputs that no one could have manipulated the results.

Thanks to Sonic's innovative Fee Monetization model, we provide secure random number generation with no additional costs beyond standard gas fees.

## Comparison With Traditional Oracle Models

| Feature                     | Traditional VRF                                                    | Paintswap VRF                                                  |
| --------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Fee Structure**           | <mark style="color:red;">Gas fees + ERC20/native token fees</mark> | <mark style="color:green;">Gas fees only</mark>                |
| **Tokens Required**         | Must hold specific tokens                                          | <mark style="color:green;">Just network gas token</mark>       |
| **Fulfillment Time**        | Multiple blocks/minutes                                            | <mark style="color:green;">Sub-second response possible</mark> |
| **Subscription Management** | Complex subscription system                                        | <mark style="color:green;">No subscriptions needed</mark>      |
| **Cost Predictability**     | Variable based on token prices                                     | <mark style="color:green;">Predictable gas costs only</mark>   |

## System Flow

1. #### Request Random Numbers

   Consumer contract calls `requestRandomnessPayInNative()` and calculates fee using the Paintswap VRF Coordinator contract.
2. #### Event Detection

   VRF Listener detects the `RandomWordsRequested` event and stores request details in a queue where they can be processed at Sonic speed.
3. #### Proof Generation

   A VRF Oracle worker generates a VRF proof using the oracle's private key and prepares the cryptographic verification parameters.
4. #### Fulfillment Submission

   Oracle submits the `fulfillRandomWords()` transaction to the Paintswap VRF contract with the request ID and VRF proof.
5. #### On-Chain Verification

   VRF contract verifies the proof, confirms it matches the commitment, and derives provable random word values.
6. #### Random Numbers Delivered

   Consumer's `rawFulfillRandomWords()` callback receives the verified random words and executes logic.

## Technical Details

**Smart Contract Architecture**

* PaintswapVRFCoordinator: Core coordinator contract with UUPS upgradeability
* PaintswapVRFConsumer: Abstract base class for contracts requesting randomness
* VRF library: Implements cryptographic functions using Secp256k1 and SHA256
* Owner Controls: Oracle registration, fee management, parameter tuning

**Oracle Worker System**

* VRF Listener: Monitors blockchain events for randomness requests
* VRF Processor: Generates cryptographic proofs and submits transactions
* Queue: Maintains workers, request state, and status tracking
* Heartbeat System: Ensures oracle health with periodic checks

**Security Properties**

* Cryptographic Verification: Elliptic curve based VRF with on-chain validation
* Distributed Processing: Multiple oracles can process requests with locking mechanism
* Retry Mechanism: Handles temporary failures with backoff strategy

## Integration Steps

1. Import `PaintswapVRFConsumer` base contract and inherit from it
2. Implement `_fulfillRandomWords()` callback
3. Store request context to match responses with requests
4. Request randomness by calling `_requestRandomnessPayInNative()`
5. Process delivered random words in your callback function

| Network       | Chain ID | VRF Coordinator                            |
| ------------- | -------- | ------------------------------------------ |
| Sonic Mainnet | 146      | 0x6E3efcB244e74Cb898A7961061fAA43C3cf79691 |
| Blaze Testnet | 57054    | 0x6E3efcB244e74Cb898A7961061fAA43C3cf79691 |

## npm Package

{% embed url="<https://www.npmjs.com/package/@paintswap/vrf>" %}

## Painswap VRF Portal

{% embed url="<https://vrf.paintswap.io/>" %}

## Media Kit

{% content-ref url="/pages/JqukDSpdf2jgd5RA1T7N" %}
[Media Kit](/misc/media-kit.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paintswap.io/paintswap-dapp-suite/vrf.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.