Epicentral Labs

https://docs.opx.markets/docs
Admin
Epicentral Labs is an organization building a decentralized ecosystem, including a DAO, a staking...
Tokens:15,733
Snippets:167
Trust Score:4.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Pool Initialization API

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

Initializes a new stake pool by creating configuration and pool accounts atomically. It sets up reward and stake mints, emission rates, and initial interest index.

```APIDOC
## POST /initialize_stake_pool

### Description
Creates a new stake pool configuration and account. This instruction atomically sets up the necessary accounts for a new staking pool.

### Method
POST

### Endpoint
/initialize_stake_pool

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **emission_bps** (u128) - Required - The emission rate in basis points (1 bps = 0.01%). Must be between `MIN_EMISSION_BPS` and `MAX_EMISSION_BPS`.
- **stake_mint** (PublicKey) - Required - The mint account for the token to be staked.
- **reward_mint** (PublicKey) - Required - The mint account for the reward token.

### Request Example
```json
{
  "emission_bps": 1000,
  "stake_mint": "stake_mint_address",
  "reward_mint": "reward_mint_address"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful pool initialization.

#### Response Example
```json
{
  "message": "Stake pool initialized successfully."
}
```

### Constraints
- `emission_bps` must be between `MIN_EMISSION_BPS` and `MAX_EMISSION_BPS`.
- `stake_mint` and `reward_mint` decimals cannot exceed 12.
- Only signers listed in the `AUTHORITIES` constant are permitted to initialize the pool.
```

--------------------------------

### Initialize Stake Pool Configuration and Account (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

The `initialize_pool_handler` function creates both the configuration and stake pool accounts atomically. It validates emission rates and mint decimals, then populates the `StakePoolConfig` and `StakePool` structs. Constraints include emission rate bounds and a maximum of 12 decimals for mints.

```rust
pub fn initialize_pool_handler(ctx: Context<InitializeStakePool>, emission_bps: u128) -> Result<()> {
    require!(
        emission_bps >= MIN_EMISSION_BPS && emission_bps <= MAX_EMISSION_BPS,
        StakingError::InvalidEmissionBps
    );
    require_gte!(
        12,
        ctx.accounts.stake_mint.decimals,
        StakingError::MintDecimalsTooHigh
    );
    require_gte!(
        12,
        ctx.accounts.reward_mint.decimals,
        StakingError::MintDecimalsTooHigh
    );
    *ctx.accounts.config = StakePoolConfig {
        reward_mint: ctx.accounts.reward_mint.key(),
        stake_mint: ctx.accounts.stake_mint.key(),
        emission_bps,
        bump: ctx.bumps.config,
    };
    *ctx.accounts.stake_pool = StakePool {
        config: ctx.accounts.config.key(),
        vault: ctx.accounts.vault.key(),
        interest_index: 0,
        interest_index_last_updated: Clock::get()?.unix_timestamp,
        bump: ctx.bumps.stake_pool,
    };

    Ok(())
}
```

--------------------------------

### Staking API

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

Handles the process of staking tokens into a stake pool. This instruction supports both new and existing stake accounts, transferring tokens to the pool's vault.

```APIDOC
## POST /stake_to_stake_pool

### Description
Allows users to stake tokens into a specified stake pool. This instruction handles the creation of new stake accounts or updates existing ones, and transfers the staked tokens to the pool's vault.

### Method
POST

### Endpoint
/stake_to_stake_pool

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (u64) - Required - The amount of tokens to stake.
- **stake_pool** (PublicKey) - Required - The address of the stake pool to stake into.
- **stake_account** (PublicKey) - Required - The user's stake account address.
- **stake_mint** (PublicKey) - Required - The mint address of the token being staked.
- **user_ata** (PublicKey) - Required - The user's associated token account for the stake mint.

### Request Example
```json
{
  "amount": 1000000,
  "stake_pool": "stake_pool_address",
  "stake_account": "user_stake_account_address",
  "stake_mint": "stake_mint_address",
  "user_ata": "user_ata_address"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful staking.

#### Response Example
```json
{
  "message": "Tokens staked successfully."
}
```

### Process
1. Validates `amount` > 0 and mint decimals.
2. Updates the Global Interest Index to the current time.
3. Creates a new `StakeAccount` if the user has no existing stake, otherwise updates the existing `StakeAccount`.
4. Transfers `stake_mint` tokens from the user's associated token account (ATA) to the pool vault.
```

--------------------------------

### Claiming Rewards API

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

Enables users to claim their accrued rewards from the stake pool. This instruction calculates pending rewards, mints new reward tokens, and updates the user's stake account.

```APIDOC
## POST /claim_rewards

### Description
Allows users to claim their accrued staking rewards. This instruction calculates the pending rewards based on the user's stake and the pool's emission rate, mints the reward tokens, and updates the user's stake account.

### Method
POST

### Endpoint
/claim_rewards

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **stake_pool** (PublicKey) - Required - The address of the stake pool.
- **config** (PublicKey) - Required - The configuration account of the stake pool.
- **stake_account** (PublicKey) - Required - The user's stake account address.
- **reward_mint** (PublicKey) - Required - The mint address of the reward token.
- **user_reward_ata** (PublicKey) - Required - The user's associated token account for the reward mint.

### Request Example
```json
{
  "stake_pool": "stake_pool_address",
  "config": "config_address",
  "stake_account": "user_stake_account_address",
  "reward_mint": "reward_mint_address",
  "user_reward_ata": "user_reward_ata_address"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful reward claim.
- **claimed_amount** (u64) - The amount of reward tokens claimed.

#### Response Example
```json
{
  "message": "Rewards claimed successfully.",
  "claimed_amount": 5000
}
```

### Process
1. Updates the Global Interest Index to the current time.
2. Calculates pending rewards using the `update_pending_rewards` utility.
3. Mints `reward_mint` tokens if `pending_rewards` > 0.
4. Resets the baseline interest index via `apply_claim`.
```

--------------------------------

### Define Stake Pool Configuration Account - Rust

Source: https://docs.opx.markets/docs/staking-lab/staking-program

Defines the `StakePoolConfig` account structure, which stores global parameters for the staking pool, including mint addresses for staked and reward tokens, emission rate, and a bump seed.

```rust
#[account(discriminator = 1)]
#[derive(InitSpace)]
pub struct StakePoolConfig {
    pub stake_mint: Pubkey,  // LABS address in this case
    pub reward_mint: Pubkey, // xLABS address in this case
    pub emission_bps: u128,  // Emission Rate in basis points (e.g., 10% is 1_000)
    pub bump: u8,
}
```

--------------------------------

### Stake Tokens to Pool (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

The `stake_handler` function manages staking operations for both new and existing user stake accounts. It validates the stake amount, updates the global interest index, initializes a new stake account if necessary, or updates an existing one. Finally, it transfers the staked tokens to the pool's vault.

```rust
pub fn stake_handler(ctx: Context<StakeToStakePool>, amount: u64) -> Result<()> {
    ctx.accounts.validate(amount)?;
    let interest_index = ctx.accounts.update_pool_interest_index()?; // we return it because it's more efficient than reloading the whole account
    if ctx.accounts.stake_account.staked_amount == 0 {
        ctx.accounts.initialize_user_stake_account(
            amount,
            ctx.bumps.stake_account,
            interest_index,
        )?;
    } else {
        require_keys_eq!(
            ctx.accounts.stake_pool.key(),
            ctx.accounts.stake_account.stake_pool,
            StakingError::StakePoolMismatch
        );

        ctx.accounts
            .update_user_stake_account(amount, interest_index)?;
    }
    ctx.accounts.transfer_to_vault(amount)?;
    Ok(())
}
```

--------------------------------

### Claim Staked Rewards (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

The `claim_handler` function facilitates the claiming of accrued rewards by minting `reward_mint` tokens. It relies on the `process_claim` utility function to update the global interest index, calculate pending rewards, mint tokens if rewards are available, and reset the interest index baseline.

```rust
pub fn claim_handler(ctx: Context<ClaimRewards>) -> Result<()> {
    ctx.accounts.validate()?;
    process_claim(
        &mut ctx.accounts.stake_pool,
        &ctx.accounts.config,
        &mut ctx.accounts.stake_account,
        &ctx.accounts.reward_mint,
        &ctx.accounts.user_reward_associated_token_account,
        &ctx.accounts.token_program,
        ctx.bumps.reward_mint,
    )?;
    Ok(())
}
```

--------------------------------

### Define User Stake Account - Rust

Source: https://docs.opx.markets/docs/staking-lab/staking-program

Defines the `StakeAccount` structure for individual user positions, storing the user's public key, the associated stake pool, staked amount, pending rewards, and the interest index at the time of deposit. Derived via PDA using `"stake_account"`, stake pool key, and user key.

```rust
#[account(discriminator = 3)]
#[derive(InitSpace)]
pub struct StakeAccount {
    pub user: Pubkey,
    pub stake_pool: Pubkey,

    // We're using u64 here because that's the SPL token standard.
    pub staked_amount: u64,
    pub pending_rewards: u64,
    pub interest_index_at_deposit: u128,
    pub bump: u8,
}
```

--------------------------------

### Define Program Authorities - Rust

Source: https://docs.opx.markets/docs/staking-lab/staking-program

Specifies the constant array `AUTHORITIES` containing the public keys of authorized entities permitted to perform administrative operations on the staking program, such as initializing or deleting stake pools.

```rust
pub const AUTHORITIES: [Pubkey; 2] = [
    pubkey!("3BEvopNQ89zkM4r6ADva18i5fao1sqR1pmswyQyfj838"), // DAO Main Treasury
    pubkey!("5aVw8DnKuxjYRhvBDkE9Khh5NbxjUyu1pjDkgS6bdNFF"), // Core Team Hot Wallet
];
```

--------------------------------

### Update Global Interest Index Calculation (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/reward-calculation-system

Calculates the growth of the Global Interest Index based on the elapsed time and the pool's emission rate. This function is crucial for maintaining an up-to-date index that reflects the passage of time and emission accrual.

```rust
pub fn update_interest_index(&mut self, now: i64, emission_bps: u128) -> Result<u128> {
    // Calculate how much time has passed
    let elapsed_seconds = now - self.interest_index_last_updated;
    
    // Calculate growth based on Emission Rate and elapsed time
    let growth = (emission_decimals * elapsed_seconds) / seconds_per_year;
    
    // Add growth to the existing index
    self.interest_index += growth;
    
    Ok(self.interest_index)
}
```

--------------------------------

### Define Stake Pool State Account - Rust

Source: https://docs.opx.markets/docs/staking-lab/staking-program

Defines the `StakePool` account structure, tracking the vault for staked tokens, a reference to its configuration, the cumulative interest index, and the last update timestamp. It's derived via PDA with the seed `"stake_pool"`.

```rust
#[account(discriminator = 2)]
#[derive(InitSpace)]
pub struct StakePool {
    pub vault: Pubkey, // the vault where the staked tokens are held
    pub config: Pubkey,
    // used to track the cumulative global interest for the pool,
    // to get the decimal of interest index, divide by 10^12
    pub interest_index: u128,
    pub interest_index_last_updated: i64, // timestamp of the last interest index update
    pub bump: u8,
}
```

--------------------------------

### Handle Unstaking Logic (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/instruction-flow

The `unstake_handler` function manages both partial and full unstakes from a stake pool. It requires a `StakePool` and `StakeAccount` context, along with the `amount` to unstake. For full unstakes, it claims rewards and closes the stake account; for partial unstakes, it updates interest indices and recalculates rewards before transferring tokens.

```rust
pub fn unstake_handler(ctx: Context<UnstakeFromStakePool>, amount: u64) -> Result<()> {
    require_keys_eq!(
        ctx.accounts.stake_pool.key(),
        ctx.accounts.stake_account.stake_pool
    );
    
    let mut should_close = false;
    if amount == ctx.accounts.stake_account.staked_amount {
        // Full unstake: claim rewards and mark for closing
        process_claim(/* ... */)?;
        should_close = true;
    } else {
        // Partial unstake: update interest and reset baseline
        let now = Clock::get()?.unix_timestamp;
        let interest_index = ctx.accounts.stake_pool
            .update_interest_index(now, ctx.accounts.config.emission_bps)?;
        ctx.accounts.stake_account.update_pending_rewards(interest_index)?;
        ctx.accounts.stake_account.interest_index_at_deposit = interest_index;
    }
    
    ctx.accounts.transfer_staked_to_user(amount)?;
    ctx.accounts.stake_account.staked_amount = ctx
        .accounts.stake_account.staked_amount
        .checked_sub(amount)
        .ok_or(StakingError::Overflow)?;
    
    if should_close {
        close_stake_account(&mut ctx.accounts.stake_account, &mut ctx.accounts.user)?;
    }
    
    Ok(())
}
```

--------------------------------

### Update Pending Rewards Calculation (Rust)

Source: https://docs.opx.markets/docs/staking-lab/staking-program/reward-calculation-system

Calculates and updates the pending rewards for a user based on the difference between the current global interest index and their baseline index at the time of deposit. This function is called when a user interacts with the pool to claim rewards.

```rust
pub fn update_pending_rewards(&mut self, current_interest_index: u128) -> Result<()> {
    // Find the difference between now and when you staked
    let index_difference = current_interest_index - self.interest_index_at_deposit;
    
    // Multiply by your staked amount
    let new_rewards = index_difference * self.staked_amount;
    
    // Add to your existing pending rewards
    self.pending_rewards += new_rewards;
    
    Ok(())
}
```
Tokens:
Raw