@pendle/sdk-boros 0.1.34 → 0.1.36

package/README.md

@@ -1 +1,568 @@
-# Pendle SDK for Boros
+# Pendle SDK Boros
+
+The `Exchange` class provides an interface for interacting with the Boros trading platform. It handles operations such as placing orders, modifying orders, managing positions, and interacting with the blockchain.
+
+Below is the documentation for the SDK. For more details about the overall architecture, contracts, API, and more, please refer to the [documentation](documentation/) folder.
+
+You can start with the [lite paper](documentation/lite-paper.md) to understand the overall architecture and mechanics of the platform.
+Then you can go to the [API docs](documentation/API.docs.md) to understand the API and parameters.
+After that, you can refer to [SDK docs](documentation/SDK.docs.md) and [example](documentation/example/) to see how to use the SDK.
+
+## Installation
+
+```bash
+yarn add @pendle/sdk-boros
+
+```
+
+## Initialization
+
+```typescript
+constructor(walletClient: WalletClient, root: Address, accountId: number)
+```
+
+The Exchange class requires three parameters for initialization:
+
+- `walletClient`: A viem WalletClient instance for signing transactions
+- `root`: The wallet address (Address type from viem)
+- `accountId`: The numerical ID of the account to interact with
+
+Example:
+```typescript
+import { createWalletClient, http } from 'viem';
+import { Exchange } from 'pendle-sdk-boros';
+
+const account = privateKeyToAccount(PRIVATE_KEY);
+
+const walletClient = createWalletClient({
+  transport: http(RPC_URL),
+  account: account,
+});
+
+const exchange = new Exchange(
+  walletClient,
+  '0xYourWalletAddress',
+  0 // accountId
+);
+```
+
+## Example Flow: Creating an Agent and Placing an Order
+
+Below is a complete example showing how to create an agent, approve it, and place an order:
+
+```typescript
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { Exchange, Agent, Side, TimeInForce, MarketAccLib } from 'pendle-sdk-boros';
+
+// Setup wallet client
+const PRIVATE_KEY = '0xYourPrivateKey';
+const RPC_URL = 'https://your-rpc-endpoint.com';
+const account = privateKeyToAccount(PRIVATE_KEY);
+const accountId = 0;
+
+const walletClient = createWalletClient({
+  transport: http(RPC_URL),
+  account: account,
+});
+
+async function placeOrderExample() {
+  const exchange = new Exchange(
+    walletClient,
+    account.address,
+    accountId
+  );
+  
+  const agent = await Agent.create(walletClient);
+  
+  const approvalTx = await exchange.approveAgent(agent);
+  console.log('Agent approved:', approvalTx);
+  const tokenId = 0;
+  const marketId = 0;
+
+  const marketAcc = MarketAccLib.pack(account.address, accountId, tokenId, marketId)
+  
+  const orderResult = await exchange.placeOrder({
+    marketAcc: marketAcc,
+    marketAddress: '0xMarketAddress',
+    ammAddresses: ['0xAmmAddress1'],
+    side: Side.LONG,
+    size: 100000000000000000000n, // 100 tokens with 18 decimals
+    limitTick: 1000,
+    tif: TimeInForce.GOOD_TIL_CANCELLED,
+    useOrderBook: true
+  });
+  
+  console.log('Order placed:', orderResult);
+  
+  return orderResult;
+}
+
+placeOrderExample()
+  .then(result => console.log('Example completed successfully'))
+  .catch(error => console.error('Error in example:', error));
+```
+
+This example demonstrates the complete flow from initializing the Exchange class to successfully placing an order. The agent creation and approval steps are required before you can place orders on the platform.
+
+## Order Management
+
+### Place Order
+
+```typescript
+async placeOrder(params: PlaceOrderParams): Promise<{
+  executeResponse: any;
+  result: { order: any };
+}>
+```
+
+Places a new order on the exchange.
+
+Parameters:
+- `marketAcc`: Use MarketAccLib to pack
+- `marketAddress`: Address of the market
+- `ammAddresses`: Array of AMM addresses
+- `side`: Trade side (Enum: Side)
+- `size`: Order size as bigint
+- `limitTick`: The tick price limit
+- `tif`: Time-in-force setting enum (GOOD_TIL_CANCELLED = 0, IMMEDIATE_OR_CANCEL = 1, FILL_OR_KILL = 2, POST_ONLY = 3)
+- `useOrderBook`: Boolean indicating whether to use the order book
+
+Example:
+```typescript
+const result = await exchange.placeOrder({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  ammAddresses: ['0xAmmAddress1', '0xAmmAddress2'],
+  side: Side.LONG,
+  size: 100000000000000000000n, // 100 tokens with 18 decimals
+  limitTick: 1000,
+  tif: TimeInForce.GOOD_TIL_CANCELLED,
+  useOrderBook: true
+});
+```
+
+### Bulk Place Orders
+
+```typescript
+async bulkPlaceOrders(orderRequests: PlaceOrderParams[]): Promise<Array<{
+  executeResponse: any;
+  result: { order: any };
+}>>
+```
+
+Places multiple orders in a single transaction.
+
+Parameters:
+- `orderRequests`: Array of PlaceOrderParams objects
+
+Example:
+```typescript
+const results = await exchange.bulkPlaceOrders([
+  {
+    marketAcc: '0xMarketAccHex1',
+    marketAddress: '0xMarketAddress1',
+    ammAddresses: ['0xAmmAddress1'],
+    side: Side.LONG,
+    size: 100000000000000000000n,
+    limitTick: 1000,
+    tif: TimeInForce.GOOD_TIL_CANCELLED,
+    useOrderBook: true
+  },
+  {
+    marketAcc: '0xMarketAccHex2',
+    marketAddress: '0xMarketAddress2',
+    ammAddresses: ['0xAmmAddress2'],
+    side: Side.SHORT,
+    size: 50000000000000000000n,
+    limitTick: 950,
+    tif: TimeInForce.POST_ONLY,
+    useOrderBook: true
+  }
+]);
+```
+
+### Modify Order
+
+```typescript
+async modifyOrder(params: ModifyOrderParams): Promise<{
+  executeResponse: any;
+  result: { order: any };
+}>
+```
+
+Modifies an existing order.
+
+Parameters:
+- `orderId`: ID of the order to modify
+- `marketAcc`: Hexadecimal market account identifier
+- `marketAddress`: Address of the market
+- `size`: New order size as bigint
+- `limitTick`: New tick price limit
+- `tif`: New time-in-force setting
+
+Example:
+```typescript
+const result = await exchange.modifyOrder({
+  orderId: '123456789',
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  size: 150000000000000000000n, // 150 tokens with 18 decimals
+  limitTick: 1050,
+  tif: TimeInForce.GOOD_TIL_CANCELLED
+});
+```
+
+### Bulk Modify Orders
+
+```typescript
+async bulkModifyOrder(orderRequests: ModifyOrderParams[]): Promise<Array<{
+  executeResponse: any;
+  result: { order: any };
+}>>
+```
+
+Modifies multiple orders.
+
+Parameters:
+- `orderRequests`: Array of ModifyOrderParams objects
+
+### Cancel Orders
+
+```typescript
+async cancelOrders(params: CancelOrdersParams): Promise<{
+  executeResponse: any;
+  result: { cancelledOrders: any };
+}>
+```
+
+Cancels one or more orders.
+
+Parameters:
+- `marketAcc`: Use MarketAccLib to get
+- `marketAddress`: Address of the market
+- `cancelAll`: Boolean indicating whether to cancel all orders
+- `orderIds`: Array of order IDs to cancel (used when cancelAll is false)
+
+Example:
+```typescript
+// Cancel specific orders
+const result = await exchange.cancelOrders({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  cancelAll: false,
+  orderIds: ['123456789', '987654321']
+});
+
+// Cancel all orders
+const result = await exchange.cancelOrders({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  cancelAll: true,
+  orderIds: []
+});
+```
+
+### Bulk Cancel Orders
+
+```typescript
+async bulkCancelOrders(cancelOrderRequests: CancelOrdersParams[]): Promise<Array<{
+  executeResponse: any;
+  result: { cancelledOrders: any };
+}>>
+```
+
+Cancels multiple orders from different markets.
+
+Parameters:
+- `cancelOrderRequests`: Array of CancelOrdersParams objects
+
+
+
+## Agent Management
+
+### Approve Agent
+
+```typescript
+async approveAgent(agent?: Agent): Promise<any>
+```
+
+Approves an agent for transaction signing.
+
+Parameters:
+- `agent`: Optional Agent instance. If not provided, a new agent will be created.
+
+Example:
+```typescript
+// Approve a new agent
+const agentApproval = await exchange.approveAgent();
+
+// Approve a specific agent
+import { Agent } from 'pendle-sdk-boros';
+const customAgent = await Agent.create(walletClient);
+const agentApproval = await exchange.approveAgent(customAgent.agent);
+```
+
+## Funds Management
+
+### Deposit
+
+```typescript
+async deposit(params: DepositParams): Promise<any>
+```
+
+Deposits funds into the exchange.
+
+Parameters:
+- `userAddress`: Address of the user
+- `collateralAddress`: Address of the collateral token
+- `amount`: Amount to deposit as bigint
+
+Example:
+```typescript
+const receipt = await exchange.deposit({
+  userAddress: '0xYourWalletAddress',
+  collateralAddress: '0xTokenAddress',
+  amount: 1000000000000000000n // 1 token with 18 decimals
+});
+```
+
+### Withdraw
+
+```typescript
+async withdraw(params: WithdrawParams): Promise<any>
+```
+
+Withdraws funds from the exchange.
+
+Parameters:
+- `userAddress`: Address of the user
+- `collateralAddress`: Address of the collateral token
+- `amount`: Amount to withdraw as bigint
+
+Example:
+```typescript
+const receipt = await exchange.withdraw({
+  userAddress: '0xYourWalletAddress',
+  collateralAddress: '0xTokenAddress',
+  amount: 1000000000000000000n // 1 token with 18 decimals
+});
+```
+
+### Cash Transfer
+
+```typescript
+async cashTransfer(params: CashTransferParams): Promise<any>
+```
+
+Transfers cash between markets.
+
+Parameters:
+- `marketId`: ID of the market
+- `isDeposit`: true if transferring from vault to marketId
+- `amount`: Amount to transfer as bigint
+
+Example:
+```typescript
+const response = await exchange.cashTransfer({
+  marketId: 1,
+  isDeposit: true,
+  amount: 1000000000000000000n // 1 token with 18 decimals
+});
+```
+
+## Position Management
+
+### Close Active Positions
+
+```typescript
+async closeActivePositions(params: CloseActivePositionsParams): Promise<any>
+```
+
+Closes active positions.
+
+Parameters:
+- `marketAcc`: Hexadecimal market account identifier
+- `marketAddress`: Address of the market
+- `type`: Type of closing ("market" or "limit")
+- `size`: Size to close as bigint
+- `rate`: Optional rate for limit closings
+
+Example:
+```typescript
+// Close with market order
+const response = await exchange.closeActivePositions({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  type: "market",
+  size: 100000000000000000000n // 100 tokens with 18 decimals
+});
+
+// Close with limit order
+const response = await exchange.closeActivePositions({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  type: "limit",
+  size: 100000000000000000000n,
+  rate: 0.05 // 5% rate
+});
+```
+
+## Settings Management
+
+### Update Settings
+
+```typescript
+async updateSettings(params: UpdateSettingsParams): Promise<any>
+```
+
+Updates account settings.
+
+Parameters:
+- `marketAcc`: Hexadecimal market account identifier
+- `marketAddress`: Address of the market
+- `leverage`: Leverage value
+- `signature`: Signature as hexadecimal
+- `agent`: Agent address as hexadecimal
+- `timestamp`: Timestamp
+
+Example:
+```typescript
+const response = await exchange.updateSettings({
+  marketAcc: '0xMarketAccHex',
+  marketAddress: '0xMarketAddress',
+  leverage: 5, // 5x leverage
+  signature: '0xSignatureHex',
+  agent: '0xAgentAddress',
+  timestamp: Math.floor(Date.now() / 1000)
+});
+```
+
+## Data Retrieval
+
+### Get Markets
+
+```typescript
+async getMarkets(params: GetMarketsParams): Promise<any>
+```
+
+Retrieves market data.
+
+Parameters:
+- `skip`: Optional number of records to skip
+- `limit`: Optional limit on the number of records
+- `isWhitelisted`: Optional filter for whitelisted markets
+
+Example:
+```typescript
+const markets = await exchange.getMarkets({
+  skip: 0,
+  limit: 10,
+  isWhitelisted: true
+});
+```
+
+### Get Order Book
+
+```typescript
+async getOrderBook(params: GetOrderBookParams): Promise<any>
+```
+
+Retrieves the order book for a market.
+
+Parameters:
+- `marketAddress`: Address of the market
+- `tickSize`: Tick size (0.00001, 0.0001, 0.001, 0.01, or 0.1)
+
+Example:
+```typescript
+const orderBook = await exchange.getOrderBook({
+  marketAddress: '0xMarketAddress',
+  tickSize: 0.001
+});
+```
+
+### Get PnL Limit Orders
+
+```typescript
+async getPnlLimitOrders(params: GetPnlLimitOrdersParams): Promise<any>
+```
+
+Retrieves PnL (Profit and Loss) limit orders.
+
+Parameters:
+- `skip`: Optional number of records to skip
+- `limit`: Optional limit on the number of records
+- `isActive`: Optional filter for active orders
+- `marketAddress`: Optional filter for a specific market
+- `orderBy`: Optional field to order by ('timeClosed', 'positionSize', 'avgFixedApr', 'avgUnderlyingApr', 'pnl')
+
+Example:
+```typescript
+const pnlOrders = await exchange.getPnlLimitOrders({
+  skip: 0,
+  limit: 10,
+  isActive: true,
+  marketAddress: '0xMarketAddress',
+  orderBy: 'pnl'
+});
+```
+
+### Get Collaterals
+
+```typescript
+async getCollaterals(): Promise<any>
+```
+
+Retrieves collateral information for the current user and account.
+
+Example:
+```typescript
+const collaterals = await exchange.getCollaterals();
+```
+
+### Get Active Positions
+
+```typescript
+async getActivePositions(params: GetActivePositionsParams): Promise<any>
+```
+
+Retrieves active positions.
+
+Parameters:
+- `marketAddress`: Optional filter for a specific market
+
+Example:
+```typescript
+// Get all active positions
+const allPositions = await exchange.getActivePositions({});
+
+// Get active positions for a specific market
+const marketPositions = await exchange.getActivePositions({
+  marketAddress: '0xMarketAddress'
+});
+```
+
+### Get Closed Positions
+
+```typescript
+async getClosedPositions(params: GetClosedPositionsParams): Promise<any>
+```
+
+Retrieves closed positions.
+
+Parameters:
+- `marketAddress`: Optional filter for a specific market
+- `skip`: Optional number of records to skip
+- `limit`: Optional limit on the number of records
+- `orderBy`: Optional field to order by ('timeClosed', 'positionSize', 'avgFixedApr', 'avgUnderlyingApr', 'pnl')
+
+Example:
+```typitten
+const closedPositions = await exchange.getClosedPositions({
+  marketAddress: '0xMarketAddress',
+  skip: 0,
+  limit: 10,
+  orderBy: 'timeClosed'
+});
+```