> For the complete documentation index, see [llms.txt](https://docs.paintswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paintswap.io/paintswap-dapp-suite/vrf.md).

# 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 %}