OIL TypeScript SDK

TypeScript SDK for interacting with the OIL program on Fogo Network (Testnet).

Installation

npm install @oilsupply/fogo-sdk @solana/web3.js @solana/spl-token

Note: This SDK is configured for Fogo Testnet. All examples use testnet endpoints and addresses.

Quick Start

import { Connection, PublicKey, Keypair, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
import {
  OIL_PROGRAM_ID,
  deriveWellPDA,
  getWellAccount,
  placeBid,
  contributeComplete,
  claimAuctionOIL,
} from '@oilsupply/fogo-sdk';

// Connect to Fogo Testnet
const connection = new Connection('https://testnet.fogo.io', 'confirmed');
const payer = Keypair.fromSecretKey(Buffer.from(JSON.parse(process.env.PRIVATE_KEY || '[]')));

PDA Derivation

import {
  deriveWellPDA,
  deriveMinerPDA,
  deriveAuctionPDA,
  deriveTreasuryPDA,
  deriveSharePDA,
  deriveMicroPDA,
} from '@oilsupply/fogo-sdk';

const wellPDA = deriveWellPDA(0);
const minerPDA = deriveMinerPDA(payer.publicKey);
const sharePDA = deriveSharePDA(payer.publicKey, 0, 123); // well, epoch

Fetching Account Data

import {
  getWellAccount,
  getAuctionAccount,
  getMinerAccount,
  getTreasuryAccount,
  getAllWellAccounts,
} from '@oilsupply/fogo-sdk';

const well = await getWellAccount(connection, 0);
const auction = await getAuctionAccount(connection);
const miner = await getMinerAccount(connection, payer.publicKey);
const wells = await getAllWellAccounts(connection);

Auction Operations

Place Bid

import { placeBid, getWellAccount, deriveMinerPDA } from '@oilsupply/fogo-sdk';

const well = await getWellAccount(connection, 0);

const instruction = placeBid(
  payer.publicKey,
  {
    wellId: 0,
    previousOwnerMiner: well?.currentBidder.equals(PublicKey.default)
      ? undefined
      : deriveMinerPDA(well.currentBidder),
    previousOwner: well?.currentBidder.equals(PublicKey.default)
      ? undefined
      : well.currentBidder,
  }
);

await sendAndConfirmTransaction(connection, new Transaction().add(instruction), [payer]);

Contribute to Pool

import { contributeComplete, getWellAccount } from '@oilsupply/fogo-sdk';

const well = await getWellAccount(connection, 0);
const instruction = contributeComplete(
  payer.publicKey,
  { wellId: 0, amount: BigInt(100_000_000) },
  well.epochId
);

await sendAndConfirmTransaction(connection, new Transaction().add(instruction), [payer]);

Claim Rewards

import { claimAuctionOIL, claimAuctionSOL, getMinerAccount, deriveMinerPDA, deriveReferralPDA } from '@oilsupply/fogo-sdk';
import { getAssociatedTokenAddressSync, OIL_MINT_ADDRESS } from '@solana/spl-token';

const miner = await getMinerAccount(connection, payer.publicKey);
const referrerMiner = miner?.referrer.equals(PublicKey.default)
  ? undefined
  : deriveMinerPDA(miner.referrer);
const referrerReferral = miner?.referrer.equals(PublicKey.default)
  ? undefined
  : deriveReferralPDA(miner.referrer);

// Claim OIL from specific wells (much easier than bitmask!)
const oilIx = claimAuctionOIL(
  payer.publicKey,
  [0, 1, 2, 3], // Array of well IDs to claim from (all 4 wells)
  referrerMiner,
  referrerReferral,
  referrerReferral ? getAssociatedTokenAddressSync(OIL_MINT_ADDRESS, referrerReferral) : undefined
);

// Or claim from just wells 0 and 2:
// const oilIx = claimAuctionOIL(payer.publicKey, [0, 2], ...);

// Claim SOL
const solIx = claimAuctionSOL(payer.publicKey, referrerMiner, referrerReferral);

await sendAndConfirmTransaction(connection, new Transaction().add(oilIx).add(solIx), [payer]);

Session-Based Operations (Gasless)

All instructions have *WithSession variants for gasless transactions:

import { placeBidWithSession, contributeWithSession } from '@oilsupply/fogo-sdk';
import { useSession } from '@fogo/sessions-sdk-react';

// In React component
const { sessionState } = useSession();

if (sessionState.status === 'established') {
  const well = await getWellAccount(connection, 0);
  const instruction = placeBidWithSession(
    sessionState,
    { wellId: 0 },
    well ? well.epochId - 1 : 0 // previous epoch ID
  );
  await sessionState.sendTransaction([instruction]);
}

Available Instructions

Auction Mining

• placeBid / placeBidWithSession - Place a bid on an auction well
• contribute / contributeWithSession - Contribute to the pool
• claimAuctionOIL / claimAuctionOILWithSession - Claim OIL rewards
• claimAuctionSOL / claimAuctionSOLWithSession - Claim SOL rewards
• checkpointAuction / checkpointAuctionWithSession - Checkpoint epoch rewards

Block Mining

• deploy / deployWithSession - Deploy SOL to prospect squares
• claimSOL / claimSOLWithSession - Claim SOL rewards
• claimOIL / claimOILWithSession - Claim OIL rewards
• checkpoint / checkpointWithSession - Checkpoint block rewards
• reloadSOL - Reload SOL from miner to automation

Staking

• deposit / depositWithSession - Deposit OIL into staking
• withdraw / withdrawWithSession - Withdraw OIL from staking
• claimYield / claimYieldWithSession - Claim SOL yield

Referrals

• createReferral / createReferralWithSession - Create referral account
• claimReferral / claimReferralWithSession - Claim referral rewards

Constants

import {
  OIL_PROGRAM_ID,
  OIL_MINT_ADDRESS,
  OIL_MINT_PROGRAM_ID,
  SOL_MINT,
  POOL_ADDRESS,
  SPLIT_ADDRESS,
  SWAP_PROGRAM,
  TOKEN_DECIMALS,
  ONE_OIL,
  INSTRUCTION_DISCRIMINATORS,
} from '@oilsupply/fogo-sdk';

IDL

The SDK includes the complete IDL for type-safe interactions:

import { IDL, getInstruction, getAccountType, getError } from '@oilsupply/fogo-sdk';

const placeBidIx = getInstruction('placeBid');
const minerType = getAccountType('Miner');
const error = getError('AmountTooSmall');

Type Definitions

All account data structures are available as TypeScript interfaces:

import type {
  WellData,
  AuctionData,
  MinerData,
  TreasuryData,
  PoolData,
  ShareData,
  MicroData,
  StakeData,
  ReferralData,
  ConfigData,
} from '@oilsupply/fogo-sdk';

License

MIT