DOCSEARCHbyAlgolia
Submit Docs

ORE Program Documentation

repository·master·Indexed 21 days ago

https://github.com/regolith-labs/ore

A Solana-based program for 'Hard Money for the Digital Age' featuring a gamified mining mechanism with ORE tokens and SOL. The documentation covers the ore-api package, including mining and admin instructions (such as Automate, ClaimORE, and Bury), program state data models, event structures (Reset, Bury, Deploy, Liq, Claim), and SDK instructions for interacting with the program.

Tokens
13.2K
Snippets
62
Records
74
Agent score
73%

What's inside ore

  1. Overview of ORE Program Instructions

    master

    The ORE program provides a suite of instructions categorized into Mining and Admin operations.

    Mining Instructions

    These instructions are used by participants to interact with the game state and claim rewards:

    • Automate: Configures a new automation.
    • Checkpoint: Checkpoints rewards from a prior round.
    • ClaimORE: Claims ORE mining rewards.
    • ClaimSOL: Claims SOL mining rewards.
    • Deploy: Deploys SOL to claim space on the board.
    • Initialize: Initializes program variables.
    • Log: Logs non-truncatable event data.
    • Reset: Resets the board for a new round.

    Admin Instructions

    These instructions are used for program governance and treasury management:

    • Bury: Executes a buy-and-bury transaction.
    • Wrap: Wraps SOL in the treasury for swap transactions.
    • SetAdmin: Re-assigns the admin authority.
    • SetFeeCollector: Updates the fee collection address.
    • SetFeeRate: Updates the fee charged per swap.

  2. ORE Program State and Data Models

    master

    The ORE program manages its state through several key data structures:

    • Automation: Tracks automation configurations.
    • Board: Tracks the current round number and timestamps.
    • Config: Stores global program configurations.
    • Miner: Tracks an individual miner's game state.
    • Round: Tracks the game state of a specific round.
    • Treasury: Manages the minting, burning, and escrowing of ORE tokens.

  3. Understand Top Miner Verification in the Reset Instruction

    master

    The reset instruction includes a verification phase designed to validate that the top_miner_info account provided by the backend matches the expected winner calculated via the on-chain RNG logic.

    Important Behavior Note: This is currently a dry-run phase. Verification failures are logged via sol_log but must not cause transaction failures or panics. The goal is to test backend infrastructure without impacting protocol stability. Verification is skipped if rewards are being split (round.top_miner == SPLIT_ADDRESS), if no RNG is available, or if no one deployed to the winning square.

  4. Prerequisites for Solana Program Deployment

    master

    Before starting the deployment runbook, ensure the following tools and environment variables are available in your environment:

    • solana-verify CLI
    • solana CLI (configured for the target network)
    • vbi (Verify Buffer Integrity) tool
    • HELIUS_API_KEY environment variable (required for RPC access via Helius)

  7. Configure the ORE CLI via environment variables

    master

    The ORE CLI is controlled primarily through environment variables. Before running commands, ensure the following variables are set in your environment:

    • KEYPAIR: Path to the Solana keypair file used for signing transactions.
    • RPC: The URL of the Solana RPC endpoint.
    • COMMAND: The specific action to perform (e.g., claim, deploy, miner).

    Some commands also require additional variables:

    • AUTHORITY: (Optional) The public key of the authority for specific actions like log_automation or checkpoint.
    • RECIPIENT: (Optional) The public key for reward transfers during a claim.
    • AMOUNT: The amount of SOL to deploy.
    • SQUARE: The specific square ID to deploy to.
    • PROVIDER: The public key of the provider (used in new_var).
    • COMMIT: The Keccak hash of the commit (used in new_var).
    • SAMPLES: The number of samples (used in new_var).
    • ID: The round ID (used in participating_miners or log_round).
    • API_BASE_URL: (Optional) The Jupiter Swap API base URL (defaults to https://lite-api.jup.ag/swap/v1).
    # Example setup
export KEYPAIR=~/.config/solana/id.json
export RPC=https://api.mainnet-beta.solana.com
export COMMAND=claim
export RECIPIENT=RecipientPublicKeyHere

# Run the CLI
./ore_cli

  8. Understand the Board account structure

    master

    The Board account is a singleton used to track the global game state in ORE. It manages round timing and economic metrics. It is defined as an OreAccount type.

    // Fields in the Board struct:
pub round_id: u64,           // The current round number.
pub start_slot: u64,         // The slot at which the current round starts mining.
pub end_slot: u64,           // The slot at which the current round ends mining.
pub production_cost_ema: u64, // The exponential moving average of production cost (lamports per whole ORE).

  9. How the reward distribution mask works

    master

    The distribution_mask() method generates a deterministic 32-bit integer used to decide how rewards are distributed across the 25 squares.

    • Mechanism: It uses a Fisher-Yates shuffle seeded by the keccak hash of the round id to select 10 unique indices out of the 25 available squares.
    • Bit Mapping: The first 25 bits of the mask represent the squares.
      • A bit set to 1 means the reward on that tile is not split.
      • A bit set to 0 means the reward on that tile is split.
    • Properties: The mask is deterministic for a given id and always contains exactly 10 bits set to 1.

  10. Structure of the ORE Config account

    master

    The Config account holds the global settings for the ORE program, divided into two main sections: AdminConfig and ProtocolConfig. This account is used to manage administrative fees and core protocol parameters like intermission periods and entropy sources.

    // The Config account is composed of:
// 1. AdminConfig: Handles administrative authority and fees.
// 2. ProtocolConfig: Handles protocol authority, fees, and timing parameters.

  11. Understand the Treasury account structure

    master

    The Treasury is a singleton account that serves two primary roles in the ORE protocol: it is the mint authority for the ORE token and the authority for the program's global token account. It tracks the state of rewards and pools within the system.

    Key fields include:

    • motherlode: The amount of ORE currently held in the motherlode rewards pool.
    • miner_rewards_factor: A Numeric value representing the cumulative ORE distributed to miners, divided by the total unclaimed ORE at the time of distribution.
    • total_refined: The current total amount of refined ORE mining rewards.
    • total_unclaimed: The current total amount of unrefined ORE mining rewards.
    #[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable, Serialize, Deserialize)]
pub struct Treasury {
    pub motherlode: u64,
    pub miner_rewards_factor: Numeric,
    pub total_refined: u64,
    pub total_unclaimed: u64,
}

  12. Configure Program Deployment Variables

    master

    Before running the deployment steps, you must define the following configuration variables in your shell environment:

    VariableDescription
    PROGRAM_IDThe on-chain program address
    MULTISIG_AUTHORITYThe Squads multisig address that controls program upgrades
    GITHUB_REPOThe GitHub repository URL for the program source
    LIBRARY_NAMEThe library name (used for binary name and temp files)

    Example configuration:

    PROGRAM_ID="oreV3EG1i9BEgiAJ8b177Z2S2rMarzak4NMv1kULvWv"
MULTISIG_AUTHORITY="7eyKjpFyTszL1JB1g3BAi7UucCQfKHPThX56ehZ9kxAh"
GITHUB_REPO="https://github.com/regolith-labs/ore"
LIBRARY_NAME="ore"
    # Program configuration - EDIT THESE FOR YOUR PROGRAM
PROGRAM_ID="oreV3EG1i9BEgiAJ8b177Z2S2rMarzak4NMv1kULvWv"
MULTISIG_AUTHORITY="7eyKjpFyTszL1JB1g3BAi7UucCQfKHPThX56ehZ9kxAh"
GITHUB_REPO="https://github.com/regolith-labs/ore"
LIBRARY_NAME="ore"