npm package: @oilsupply/fogo-sdk
Description: TypeScript SDK for interacting with the OIL program on Fogo Network
Latest version: 0.1.0

# OIL TypeScript SDK

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

## Installation

```bash
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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:

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

## License

MIT