Skip to main content
Pyth Entropy is an on-chain random number generator (RNG) that provides cryptographically secure, verifiable randomness for blockchain applications. Entropy uses a two-party commit-reveal protocol, a well-known protocol in the cryptography space for generating a random number, offering lower fees, direct integration with Pyth Network, scalability, and faster response times compared to traditional VRF solutions. Entropy delivers randomness that is trustless, low-latency, cost-efficient, and requires no registration.

What You’ll Be Doing in This Guide

In this tutorial, you’ll learn how to:
  1. Integrate Pyth Entropy’s commit-reveal randomness system into your Sei EVM application
  2. Create smart contracts that request and consume verifiable random numbers using the Entropy protocol
  3. Implement a complete gaming application with fair, transparent randomness
  4. Handle fees, callbacks, and error management for production-ready randomness
By the end of this guide, you’ll have a working demo that can request cryptographically secure random numbers on the Sei network with proper verification mechanisms using Pyth Entropy.

Prerequisites

Before starting this tutorial, ensure you have:

Technical Requirements

  • Solidity Knowledge: Basic understanding of Solidity smart contract development
  • JavaScript/Node.js: For off-chain interaction and frontend integration
  • Development Environment: Remix IDE, Hardhat, Foundry, or similar Solidity development setup
  • Sei Network Access: RPC endpoint and familiarity with Sei’s EVM environment
  • Native Tokens: SEI tokens required for paying Entropy request fees

Required Dependencies

  • Pyth Entropy Solidity SDK (@pythnetwork/entropy-sdk-solidity)

Install

Sei Network Configuration

Make sure your development environment is configured for Sei:
  • Mainnet RPC: https://evm-rpc.sei-apis.com
  • Chain ID: 1329 (mainnet)
  • Testnet RPC: https://evm-rpc-testnet.sei-apis.com
  • Testnet Chain ID: 1328 (testnet)

Pyth Entropy Architecture Overview

Entropy uses a two-party commit-reveal protocol consisting of:
  1. Entropy Provider: Off-chain service that commits to a sequence of random numbers using hash chains
  2. User Commitment: Users contribute their own random input to ensure unpredictability
  3. Commit-Reveal Protocol: Two-party system where both parties contribute to final randomness
  4. On-Chain Verification: Smart contracts verify the randomness proofs and execute callbacks
  5. Keeper Network: Decentralized bots that fulfill randomness requests by revealing provider commitments

Key Concepts

Before implementing, it’s important to understand the key aspects of working with Pyth Entropy:

Two-Phase Process

Entropy uses a two-phase approach:
  • Request Phase: Your contract calls entropy.requestV2() and receives a sequenceNumber
  • Fulfillment Phase: Off-chain keepers fulfill the request by calling your contract’s entropyCallback() method

Asynchronous Nature

Unlike synchronous random number generation, Entropy requests are asynchronous:
  • The random number is not available immediately after the request
  • Your application must handle the waiting period (typically 1-3 blocks)
  • Use events and polling to know when randomness is fulfilled

Fee Management

Entropy requires payment for each randomness request:
  • Always call getFeeV2() to get the current fee before making requests
  • Fees are paid in the native token (SEI) as msg.value
  • Fees are dynamic and may change based on network conditions

Callback Implementation

Your contract must implement the entropyCallback function:
  • This method is called automatically when randomness is fulfilled
  • It receives the sequenceNumber, providerAddress, and randomNumber
  • All your game logic should be handled in this callback

Sequence Number Tracking

Each request has a unique sequenceNumber:
  • Use this to map requests to your application state
  • Store game/request data using the sequence number as the key
  • Multiple requests can be pending simultaneously

Error Handling

Always implement proper error handling:
  • Requests can fail or timeout
  • Network issues may prevent fulfillment
  • Have fallback mechanisms for failed requests

Gas Considerations

The callback execution has gas limits:
  • Keep callback logic simple to avoid out-of-gas errors
  • For complex logic, consider using custom gas limits with requestV2 variants
  • Store expensive computations for later execution

Steps to Integrate Pyth Entropy into Sei

Step 1: Smart Contract Integration

Create a consumer contract that integrates with Pyth Entropy:
Deploy this contract using Remix with the Entropy contract address for your target network: Note: Entropy V2 uses a default provider system, so you no longer need to specify a provider address in the constructor.

Step 2: JavaScript Integration for Entropy Management

Create a module to interact with Entropy and manage randomness requests: Note: The JavaScript examples below use CommonJS (require/module.exports). If your project uses "type": "module", rename these files to .cjs or convert the snippets to ES Modules.

Step 3: Complete Integration Example

Here’s a simple usage example that puts it all together: First, create a .env file in your project root (never commit this file):
Then create the demo script:

Expected Output

To run the complete demo, execute the demo.js script:
When you run the Pyth Entropy integration, you should see output similar to:

Data Structure Details

Pyth Entropy V2 responses include several important fields:
  • sequenceNumber: Unique identifier for the randomness request (uint64)
  • randomNumber: The cryptographically secure random bytes32 value
  • providerAddress: Address of the entropy provider that fulfilled the request
  • blockNumber: Block number when the request was fulfilled

Fee Structure

  • Dynamic Fees: Always use the on-chain method entropy.getFeeV2() to get the current fee
  • Native Token Payment: Fees are paid in the native blockchain token (SEI)
  • Per-Request Basis: Each randomness request has its own fee
  • No User Commitment Required: Entropy V2 simplifies the process by removing the need for user random numbers

Best Practices

  1. Fee Management: Always check current fees using getFeeV2() before submitting requests
  2. Callback Gas Limits: Set appropriate gas limits for complex callback logic using Entropy V2’s custom gas limit features
  3. Error Handling: Implement proper timeout and error handling for unfulfilled requests
  4. Sequential Processing: Handle multiple requests appropriately as they may be fulfilled out of order
  5. Storage Optimization: Remember that fulfilled randomness is not stored by the contract - save it if needed for multiple uses

Resources