entropy-rng-api

API crate for interacting with the Entropy RNG (Random Number Generator) program on Solana.

Entropy is a provably-fair random number generation protocol for Solana. It uses a commit-reveal scheme paired with slothash sampling strategy to generate random numbers on-chain in a secure and cost-effective way.

Features

• ✅ Instruction builders for all Entropy RNG instructions
• ✅ State types and account deserialization
• ✅ PDA derivation utilities
• ✅ SDK functions for common operations
• ✅ Type-safe error handling

Installation

Add to your Cargo.toml:

[dependencies]
entropy-rng-api = "0.1.1"

Quick Start

use entropy_rng_api::prelude::*;

// Derive a Var PDA
let seed = b"my-seed";
let (var_pda, _bump) = var_pda(&seed);

// Build an Open instruction
let instruction = open(
    signer,
    var_address,
    commit,
    end_slot,
    is_auto,
);

Modules

Instructions

• Open - Opens a new variable account
• Close - Closes a variable account
• Next - Moves a variable to the next value
• Reveal - Reveals a seed to finalize the variable value
• Sample - Samples the slothash from the chain

State

• Var - Variable account that tracks a unique random variable

SDK

Helper functions for:

• PDA derivation
• Instruction building
• Account deserialization

How It Works

1. Open: Create a new variable with a commit from the Entropy API
2. Sample: Sample the slothash from the chain at the specified slot
3. Reveal: Reveal the seed to finalize the variable value
4. Next: Reset the variable for its next value (using previous seed as new commit)

The protocol ensures provably-fair randomness by:

• Committing to future seeds before the slothash is known
• Using on-chain slothash that's unpredictable at commit time
• Keeping future seeds secret until reveal time

Example

use entropy_rng_api::prelude::*;
use solana_program::pubkey::Pubkey;

// Derive variable PDA
let seed = b"my-random-seed";
let (var_pda, _bump) = var_pda(&seed);

// Build Open instruction
let open_ix = open(
    &signer.pubkey(),
    &var_pda,
    commit,           // From Entropy API
    end_slot,         // Target slot
    false,            // is_auto
);

// Build Sample instruction
let sample_ix = sample(
    &signer.pubkey(),
    &var_pda,
);

// Build Reveal instruction
let reveal_ix = reveal(
    &signer.pubkey(),
    &var_pda,
    seed_value,       // From Entropy API after sampling
);

Documentation

Full API documentation is available at:

• docs.rs: https://docs.rs/entropy-rng-api
• Repository: https://github.com/oil-protocol/entropy-rng

License

Licensed under Apache-2.0

Related

• Entropy Program - The on-chain Solana program
• Entropy CLI - Command-line tools