npm package: @rakurai/rakurai-stake-sdk
Description: TypeScript SDK for Rakurai liquid SOL stake and unstake on Solana—builds transactions from the Rakurai API for signing with @solana/web3.js, plus campaign, raisol apy and price, and referral helpers.
Author: Rakurai
Latest version: 1.1.1

# @rakurai/rakurai-stake-sdk

TypeScript helpers for Rakurai liquid stake / unstake flows. The SDK calls the APIs, deserializes returned transactions, and returns Solana `Transaction` / `VersionedTransaction` objects you can sign and send with `@solana/web3.js`.

**Peer dependency:** `@solana/web3.js` (see [Install in a consumer project](#install-in-a-consumer-project)).

**API base URL:** HTTP endpoints live in `src/rakurai-stake-sdk.ts` (defaults point at Rakurai’s API). Change those constants if you need another environment.

---

## Wrapper functions

The exported helpers are **wrappers around Rakurai’s HTTP APIs**: they perform the requests, interpret the JSON, and hand you **`Transaction` / `VersionedTransaction`** instances from `@solana/web3.js` where the flow builds an on-chain transaction, plus **plain API JSON responses** where the endpoint returns JSON data only.

---

## Install in a consumer project

Install this package and `@solana/web3.js` from your consumer app directory.

### 1. Install with npm (recommended)

```bash
npm install @rakurai/rakurai-stake-sdk@^1.1.1 @solana/web3.js@^1.98.0
```

npm writes those entries into `package.json` under `dependencies` and updates `package-lock.json`. You don’t need to copy the versions by hand.

### 2. Edit `package.json`

Add under `"dependencies"`:

```json
"@rakurai/rakurai-stake-sdk": "^1.1.1",
"@solana/web3.js": "^1.98.0"
```

Then run:

```bash
npm install
```

---

## API functions

Import from the package entry (types are exported for TypeScript):

```ts
import {
  RaiSOLStakeError,
  liquidStake,
  liquidUnstake,
  liquidUnstakeJupiter,
  updateCampaign,
  getReferral,
  getRaiSOLApy,
  getRaiSOLPrice,
} from '@rakurai/rakurai-stake-sdk';
import type {
  StakeParams,
  UnstakeParams,
  UnstakeJupiterParams,
  UnstakeResult,
  CampaignUpdateParams,
  CampaignUpdateResponse,
  ReferralDetailsResponse,
} from '@rakurai/rakurai-stake-sdk';
```

Handle errors with `instanceof RaiSOLStakeError`; use `error.message` and optional `error.code` (HTTP-style status when available).

### `liquidStake(params: StakeParams)`

- **Purpose:** Request a liquid-stake transaction from the API and deserialize it as a **versioned** transaction.
- **Parameters:** `StakeParams` — `{ pubkey: string; amount: number }`: user wallet (base58); `amount` is a **positive integer** in lamports (for a 1 SOL stake, use `1000000000` in `amount`).
- **Returns:** `Promise<VersionedTransaction>`
- **After:** Sign with the user’s wallet and send the transaction on-chain.

```ts
const TEST_PUBKEY = 'E2AuCLjPeHQEVKxMGRPUfWetMLMM8nYnR52weHVALNv3';
const TEST_AMOUNT = 10000;

const tx = await liquidStake({
  pubkey: TEST_PUBKEY,
  amount: TEST_AMOUNT,
});
```

### `liquidUnstake(params: UnstakeParams)`

- **Purpose:** Request a **legacy** unstake transaction plus the stake-account keypair.
- **Parameters:** `UnstakeParams` — `{ pubkey: string; amount: number }`: same rules as stake (base58 `pubkey`, integer `amount`).
- **Returns:** `Promise<UnstakeResult>` — `{ transaction, stakeAccountKeypair }`
- **After:** Sign the returned `transaction` with the user’s wallet, partially sign with the returned `stakeAccountKeypair` as required, then send.

```ts
const { transaction, stakeAccountKeypair } = await liquidUnstake({
  pubkey: TEST_PUBKEY,
  amount: TEST_AMOUNT,
});
```

### `liquidUnstakeJupiter(params: UnstakeJupiterParams)`

- **Purpose:** Jupiter route for liquid unstake; returns a **versioned** transaction.
- **Parameters:** `UnstakeJupiterParams` — `{ pubkey: string; amount: number }`: base58 `pubkey`, integer `amount`.
- **Returns:** `Promise<VersionedTransaction>`
- **After:** Sign with the user’s wallet and send.

```ts
const tx = await liquidUnstakeJupiter({
  pubkey: TEST_PUBKEY,
  amount: TEST_AMOUNT,
});
```

### `updateCampaign(params: CampaignUpdateParams)`

- **Purpose:** Notify the campaign / referral backend **after** a stake or unstake has landed (you pass the on-chain signature).
- **Parameters:** `CampaignUpdateParams` — `address` (wallet base58), `amount` (positive integer), `txn_sig`, `is_stake`, `referral_code`
- **Returns:** `Promise<CampaignUpdateResponse>` (`message?`, `error?`)
- **After:** Use the response for success or errors in the UI or logs. Call it with the required parameters each time a stake or unstake transaction is confirmed. Set `is_stake` to `true` for stake transactions and `false` for unstake transactions.

```ts
const res = await updateCampaign({
  address: TEST_PUBKEY,
  amount: TEST_AMOUNT,
  txn_sig: signature,
  is_stake: true,
  referral_code: 'MYCODE',
});
```

### `getReferral(referral_code: string)`

- **Purpose:** Fetch referral stats for a code.
- **Parameters:** `referral_code` (string, query param).
- **Returns:** `Promise<ReferralDetailsResponse>` (`referral_code?`, `no_of_referrals?`, `referral_staked_amount?`, `error?`)
- **After:** Use fields such as `no_of_referrals` as needed.

```ts
const details = await getReferral('MYCODE');
```

### `getRaiSOLApy()`

- **Purpose:** Fetch the APY for Rakurai’s liquid staking pool.
- **Parameters:** None.
- **Returns:** `Promise<number>` — the APY value (e.g. `7.11...`). On HTTP or parse errors, throws `RaiSOLStakeError`.

```ts
const apy = await getRaiSOLApy();
```

### `getRaiSOLPrice()`

- **Purpose:** Fetch the price of 1 `raiSOL` denominated in `SOL`.
- **Parameters:** None.
- **Returns:** `Promise<number>` — price in SOL terms (e.g. `1.263`). On HTTP or parse errors, throws `RaiSOLStakeError`.

```ts
const priceInSol = await getRaiSOLPrice();
```

---