npm package: @noman1344/raisol-stake
Description: SDK for staking SOL to receive raiSOL via Rakurai stake pool
Author: Rakurai
Latest version: 2.0.1

# @noman1344/raisol-stake

TypeScript helpers for Rakurai liquid stake / unstake flows. The SDK calls your Rakurai backend, 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/stake_unstake_apis.ts` (defaults point at Rakurai’s API). Change those constants if you need another environment.

---

## Wrapper functions (what they do)

These helpers **POST to the Rakurai staking APIs**, read the JSON (hex-encoded transaction bytes, and for classic unstake also stake-account keys), and **return ready-to-use Solana transactions** from `@solana/web3.js`. They do **not** sign or submit anything on-chain.

| Concern | Detail |
|--------|--------|
| **Purpose** | Avoid hand-calling the REST API and deserializing `txn` hex yourself. |
| **Parameters** | JSON bodies match the backend: `pubkey` (string), `amount` (positive **integer** in the units your API expects—typically lamports or smallest token units, not SOL floats). |
| **Response** | A `VersionedTransaction`, a legacy `Transaction`, or (unstake) `UnstakeResult` with `transaction` + `stakeAccountKeypair`. |
| **After the call** | **Stake / Jupiter unstake:** sign with the user’s wallet (fee payer) and **send** via `Connection.sendTransaction` (or your wallet adapter). **Classic unstake:** sign with the user wallet **and** the returned `stakeAccountKeypair` as required by the transaction, then send. Persist the returned stake keypair securely if the flow needs it later. |

**Public key string:** Solana addresses are usually shown as **base58** text (e.g. `E2AuCLjPeHQEVKxMGRPUfWetMLMM8nYnR52weHVALNv3`). That is what the API expects for `pubkey`. If you have a `PublicKey` from `@solana/web3.js`, `.toBase58()` produces the same string; a plain constant is fine when you already have the address as text.

---

## 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 @noman1344/raisol-stake@^2.0.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
"@noman1344/raisol-stake": "^2.0.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,
  createLiquidStakeTransaction,
  createLiquidUnstakeTransaction,
  createLiquidJupiterUnstakeTransaction,
  updateCampaignActivity,
  getReferralDetails,
} from '@noman1344/raisol-stake';
import type {
  StakeParams,
  UnstakeParams,
  UnstakeJupiterParams,
  UnstakeResult,
  CampaignUpdateParams,
  CampaignUpdateResponse,
  ReferralDetailsResponse,
} from '@noman1344/raisol-stake';
```

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

### `createLiquidStakeTransaction(params: StakeParams)`

- **Purpose:** Request a liquid-stake transaction from the API and deserialize it as a **versioned** transaction.
- **Parameters:** `{ pubkey: string; amount: number }` — user wallet address (base58 string); `amount` is a **positive integer** in lamports (for 1 SOL stake, write 1000000000 in amount field)
- **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 createLiquidStakeTransaction({
  pubkey: TEST_PUBKEY,
  amount: TEST_AMOUNT,
});

```

### `createLiquidUnstakeTransaction(params: UnstakeParams)`

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

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

### `createLiquidJupiterUnstakeTransaction(params: UnstakeJupiterParams)`

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

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

### `updateCampaignActivity(params: CampaignUpdateParams)`

- **Purpose:** Notify the campaign / referral backend **after** a stake or unstake has landed (you pass the on-chain signature).
- **Parameters:** `address` (wallet base58 string), `amount` (positive integer), `txn_sig`, `is_stake`, `referral_code`
- **Returns:** `Promise<CampaignUpdateResponse>`
- **After:** Use the response for success and error in UI or logging. Call it everytime with the required parameters when the transaction stake or unstake transaction is confirmed.

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

### `getReferralDetails(referral_code: string)`

- **Purpose:** Fetch referral stats for a code.
- **Parameters:** `referral_code` string (query param).
- **Returns:** `Promise<ReferralDetailsResponse>`
- **After:** Use fields like `no_of_referrals` accordingly. 

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

---

## TypeScript

Consumer projects should use a recent TypeScript version and `moduleResolution` compatible with Node (e.g. `"moduleResolution": "node"` or `"bundler"`). Types ship with the package via `dist/index.d.ts`.