# Stable Points (SP)

Build on Spree Protocol with the `@spree-finance/spree-evm-sdk`. The SDK builds unsigned transactions for offline signing and executes read-only calls against Spree smart contracts.

### Install

```bash
npm install @spree-finance/spree-evm-sdk
```

### Quick Start

```typescript
import { Factory, Points } from '@spree-finance/spree-evm-sdk';

// Configure the Factory wrapper
const factory = new Factory({
  rpcUrl: 'https://sepolia.base.org',
  chainId: 84532n,
  contractAddress: '0xFactoryAddress',
  from: '0xYourWallet',
  defaultGasPriceWei: 1_000_000_000n,
  defaultGasLimit: 500_000n,
});

// Read SP balance (no transaction, uses eth_call)
const points = new Points({ ...pointsConfig });
const balance = await points.readBalanceOf('0xUserAddress');

// Build an unsigned mint transaction
const unsignedTx = await factory.mint(
  '0xUSDCAddress',  // stablecoin asset
  1_000_000n,       // amount (6 decimals for USDC)
  '0xReceiver',     // SP recipient
  false,            // expectBasketMode
);

// Sign with your wallet, then broadcast
```

### Contract Wrappers

The SDK ships one wrapper per contract. Each wrapper accepts `BaseContractConfig` and exposes both write methods (return unsigned tx hex) and read methods (return decoded values).

| Wrapper               | Contract            | Purpose                              |
| --------------------- | ------------------- | ------------------------------------ |
| `Factory`             | Factory             | Mint SP, redeem SP, vault management |
| `Points`              | Points              | ERC-20 SP token, transfer whitelist  |
| `SpreeVault4626`      | SpreeVault4626      | ERC-4626 rewards vault               |
| `BonusRewardsVault`   | BonusRewardsVault   | Epoch-based bonus rewards            |
| `PythPriceOracle`     | PythPriceOracle     | Price feeds                          |
| `PendingSPVault`      | PendingSPVault      | Campaign-based pSP distribution      |
| `SpreeStatusRegistry` | SpreeStatusRegistry | Tier/status management               |
| `BoostEngine`         | BoostEngine         | Boost multiplier calculations        |

### Additional Modules

| Module             | Purpose                                 |
| ------------------ | --------------------------------------- |
| `ClientOnboarding` | Deploy brand infrastructure             |
| `ContractRegistry` | Query deployed factories and contracts  |
| `ERC20`            | Generic ERC-20 approve/transfer/balance |

### Guides

* [Authentication](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/authentication/README.md) - API keys, auth headers, base URLs
* [Core Token Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/core-token-operations/README.md) - Mint, transfer, balance, vault creation
* [Campaign & pSP Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/campaign-operations/README.md) - Create campaigns, distribute pSP
* [Whitelist Management](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/whitelist-management/README.md) - Transfer and settlement whitelists
* [Redemption Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/redemption-operations/README.md) - Redeem SP back to stablecoins
* [API Reference](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/api-reference/README.md) - HTTP API endpoints
* [SDK Reference](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/sdk-reference/README.md) - Full SDK method signatures
* [Security & Role Management](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/security-role-management/README.md) - RBAC, freeze, upgradeability
* [Error Handling](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/error-handling/README.md) - Error classes, fee schedule
* [Join Ecosystem](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/join-ecosystem/README.md) - Get started as a brand or developer