# SDK

## SDK

The Risk Protocol SDK is a TypeScript library for interacting with Risk Protocol's core smart contracts and services. Built on ethers.js v6, it provides a complete interface for token management, vault operations, rebalancing, and price estimation.

### Installation

```bash
npm install risk-contracts
# or
yarn add risk-contracts
## Note that it's not published yet, the above is a placeholder
```

### Quick Start

#### Server-Side (Node.js)

```typescript
import { RiskContracts, RiskSdkConfig } from 'risk-contracts';

const config: RiskSdkConfig = {
  serverProvider: {
    rpcUrl: "https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY",
    privateKey: "YOUR_PRIVATE_KEY"
  },
  network: {
    name: "sepolia",
    chainId: 11155111
  },
  tokenFactory: {
    address: "0x8888cF3da8E6Fb30bEEcD9dC1dd220060c2969DC"
  },
  smartToken: {
    one: "0x...",  // RiskON token address
    two: "0x..."   // RiskOFF token address
  },
  orchestrator: {
    address: "0x..."
  },
  apiUrl: "https://api.riskprotocol.com"
};

const sdk = new RiskContracts(config);
```

#### Client-Side (Browser with Wallet)

```typescript
import { RiskContracts, RiskSdkConfig } from 'risk-contracts';
import { ethers } from 'ethers';

// Connect to user's wallet
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const config: RiskSdkConfig = {
  clientProvider: {
    provider: provider,
    signer: signer
  },
  network: {
    name: "sepolia",
    chainId: 11155111
  },
  tokenFactory: {
    address: "0x..."
  },
  smartToken: {
    one: "0x...",
    two: "0x..."
  },
  orchestrator: {
    address: "0x..."
  },
  apiUrl: "https://api.riskprotocol.com"
};

const sdk = new RiskContracts(config);
```

### Configuration

The SDK requires a configuration object that specifies network settings, contract addresses, and provider details.

```typescript
interface RiskSdkConfig {
  // Provider (choose one)
  serverProvider?: {
    rpcUrl: string;
    privateKey: string;
  };
  clientProvider?: {
    provider: ethers.BrowserProvider;
    signer: ethers.JsonRpcSigner;
  };

  // Network configuration
  network: {
    name: string;
    chainId: number;
  };

  // Contract addresses
  tokenFactory: {
    address: string;
  };
  smartToken: {
    one: string;    // RiskON address
    two: string;    // RiskOFF address
  };
  orchestrator: {
    address: string;
  };

  // Optional: API URL for NTV price estimates
  apiUrl?: string;
}
```

**Important:** Provide either `serverProvider` or `clientProvider`, not both.

### Core Concepts

#### SDK Structure

The SDK exposes five main modules:

* **tokenFactory** - Core token operations, management fees, and rebalancing
* **smartToken** - ERC-4626 vault operations (deposits, withdrawals, transfers)
* **orchestrator** - Scheduled operations and Balancer pool management
* **balancerHelper** - Balancer pool calculations and swap estimations
* **priceEstimates** - Price discovery and slippage calculations

#### Working with Amounts

All token amounts in the SDK use **wei units** (BigInt). Use ethers.js utilities for conversion:

```typescript
import { ethers } from 'ethers';

// Convert to wei
const amount = ethers.parseEther("1.5");  // 1500000000000000000n

// Convert from wei
const readable = ethers.formatEther(amount);  // "1.5"

// For tokens with different decimals
const usdcAmount = ethers.parseUnits("100", 6);  // 6 decimals
```

#### Smart Tokens

Risk Protocol uses two smart tokens: **RiskON** (index 0) and **RiskOFF** (index 1). Most SmartToken methods accept an optional `contract` parameter:

```typescript
// RiskON 
await sdk.smartToken.balanceOf(address, 0);

// RiskOFF 
await sdk.smartToken.balanceOf(address, 1);
```

### Common Workflows

#### 1. Deposit Tokens

```typescript
import { ethers } from 'ethers';

const depositAmount = ethers.parseEther("100");
const userAddress = "0x...";

// 1. Preview the deposit
const sharesReceived = await sdk.smartToken.transaction.previewDeposit(
  depositAmount.toString(),
  0  // RiskON
);

console.log(`Will receive ${ethers.formatEther(sharesReceived)} shares`);

// 2. Approve token spending (get smart token address first)
const baseToken = await sdk.tokenFactory.getBaseToken();
const riskOnAddress = await sdk.tokenFactory.getSmartTokenAddress(0);
const erc20 = new ethers.Contract(
  baseToken,
  ['function approve(address,uint256) returns (bool)'],
  signer
);

const approveTx = await erc20.approve(
  riskOnAddress,
  depositAmount
);
await approveTx.wait();

// 3. Execute deposit
const depositTx = await sdk.smartToken.transaction.deposit(
  depositAmount.toString(),
  userAddress,
  0
);
await depositTx.wait();

console.log('Deposit successful!');
```

#### 2. Withdraw Tokens

```typescript
import { ethers } from 'ethers';

const withdrawAmount = ethers.parseEther("50");
const userAddress = "0x...";

// 1. Preview withdrawal
const assetsReceived = await sdk.smartToken.transaction.previewWithdraw(
  withdrawAmount.toString(),
  0
);

console.log(`Will receive ${ethers.formatEther(assetsReceived)} assets`);

// 2. Execute withdrawal
const withdrawTx = await sdk.smartToken.transaction.withdraw(
  withdrawAmount.toString(),
  userAddress,
  userAddress,
  0
);
await withdrawTx.wait();

console.log('Withdrawal successful!');
```

#### 3. Check Balances and Fees

```typescript
import { ethers } from 'ethers';

const userAddress = "0x...";

// Get share balance (RiskON)
const shares = await sdk.smartToken.balanceOf(userAddress, 0);
console.log(`Shares: ${ethers.formatEther(shares)}`);

// Get management fee rate
const feeRate = await sdk.tokenFactory.managementFees.getRate();
const feeRateBps = Number(feeRate) / 1e14;  // Convert to basis points
console.log(`Management fee: ${feeRateBps} bps`);

// Check if fees are active
const isActive = await sdk.tokenFactory.managementFees.isFeeActive();
console.log(`Fees active: ${isActive}`);
```

#### 4. Estimate Swap Outputs

```typescript
import { ethers } from 'ethers';

const poolAddress = "0x...";
const riskOnAddress = await sdk.tokenFactory.getSmartTokenAddress(0);
const riskOffAddress = await sdk.tokenFactory.getSmartTokenAddress(1);
const amountIn = ethers.parseEther("10");

// Estimate swap output (RiskON → RiskOFF)
const expectedOut = await sdk.balancerHelper.getExpectedAmountOut(
  poolAddress,
  riskOnAddress,   // RiskON
  riskOffAddress,  // RiskOFF
  amountIn
);

console.log(`Swapping 10 RiskON`);
console.log(`Expected output: ${ethers.formatEther(expectedOut)} RiskOFF`);

```

####

### Error Handling

Always wrap SDK calls in try-catch blocks:

```typescript
try {
  const tx = await sdk.smartToken.transaction.deposit(
    amount.toString(),
    recipient,
    0
  );
  await tx.wait();
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    console.error('Insufficient funds for gas');
  } else if (error.code === 'CALL_EXCEPTION') {
    console.error('Transaction reverted:', error.reason);
  } else {
    console.error('Transaction failed:', error.message);
  }
}
```

### Best Practices

#### 1. Always Preview Before Executing

```typescript
// Always preview first to show users what they'll receive
const preview = await sdk.smartToken.transaction.previewDeposit(amount, 0);
console.log(`You will receive ${ethers.formatEther(preview)} shares`);

```

#### 2. Check Maximum Limits

```typescript
const maxDeposit = await sdk.smartToken.transaction.maxDeposit(address, 0);

if (BigInt(amount) > maxDeposit) {
  throw new Error(`Amount exceeds maximum: ${ethers.formatEther(maxDeposit)}`);
}
```

### TypeScript Support

The SDK is fully typed. Import types as needed:

```typescript
import { RiskContracts, RiskSdkConfig } from 'risk-contracts';
import type { ethers } from 'ethers';

// All methods return properly typed values
const balance: bigint = await sdk.smartToken.balanceOf(address, 0);
```

### Next Steps

* See the API Reference for complete method documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.riskprotocol.io/apis-and-sdk/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.