riskmarket-sdk 1.1.1

package/README.md

@@ -0,0 +1,440 @@
+# RiskMarket SDK Documentation
+
+## Overview
+
+RiskMarket SDK is designed as a **clean, modular, and extensible TypeScript SDK** for interacting with the RiskMarket protocol on **Arbitrum** and preparing on-chain transactions.
+
+The SDK provides a single entry point through the `Market` class, which offers:
+
+- **Read Methods** → Fetching on-chain data (market state, round info, position data, min open amount)
+- **Write Methods** → Building encoded transaction calldata (open position, cash out)
+
+---
+
+## Installation
+
+```bash
+npm install riskmarket-sdk
+```
+
+or
+
+```bash
+yarn add riskmarket-sdk
+```
+
+## Initialization
+
+```ts
+import { Market } from "riskmarket-sdk";
+
+const market = new Market();
+```
+
+The constructor accepts an optional `MarketOptions` object to configure the environment:
+
+```ts
+import { Market } from "riskmarket-sdk";
+
+const market = new Market({ environment: "production" });
+```
+
+### MarketOptions
+
+| Option        | Type          | Default         | Description                                      |
+| ------------- | ------------- | --------------- | ------------------------------------------------ |
+| `environment` | `Environment` | `"development"` | Target environment: `"development"`, `"staging"`, or `"production"` |
+
+> The constructor initializes an internal viem `PublicClient` connected to Arbitrum mainnet using the configuration for the selected environment.
+
+---
+
+## Read Methods
+
+### getMarketIndexTermination
+
+Fetches the current market round index.
+
+#### Method Signature
+
+```ts
+getMarketIndexTermination(): Promise<bigint>
+```
+
+#### Returns
+
+`bigint` — The current market round index.
+
+#### Example
+
+```ts
+const currentIndex = await market.getMarketIndexTermination();
+console.log(currentIndex); // 1363n
+```
+
+---
+
+### getMarketRoundByIndex
+
+Fetches market round data for a specific index.
+
+#### Method Signature
+
+```ts
+getMarketRoundByIndex(index: number): Promise<MarketRound>
+```
+
+#### Parameters
+
+| Parameter | Type     | Required | Description           |
+| --------- | -------- | -------- | --------------------- |
+| `index`   | `number` | ✅       | The market round index |
+
+#### Returns
+
+`MarketRound` — Market round data with all values as strings.
+
+| Field                     | Type     | Description                    |
+| ------------------------- | -------- | ------------------------------ |
+| `marketState`             | `string` | Current state of the market    |
+| `index`                   | `string` | Market round index             |
+| `startTime`               | `string` | Unix timestamp of round start  |
+| `totalAssets`             | `string` | Total assets in the round      |
+| `requestId`               | `string` | VRF request ID                 |
+| `encryptedMarketDuration` | `string` | Encrypted market duration hash |
+| `extraData`               | `string` | Additional encoded data        |
+
+#### Example
+
+```ts
+const round = await market.getMarketRoundByIndex(3);
+console.log(round.index);       // "3"
+console.log(round.marketState); // "3"
+console.log(round.startTime);   // "1767267308"
+console.log(round.totalAssets); // "9500000"
+```
+
+---
+
+### getMinOpen
+
+Fetches the minimum position amount allowed to open a market position.
+
+#### Method Signature
+
+```ts
+getMinOpen(): Promise<string>
+```
+
+#### Returns
+
+`string` — The minimum position amount converted from Wei (mwei / 6 decimals).
+
+#### Example
+
+```ts
+const minOpen = await market.getMinOpen();
+console.log(minOpen); // "1.000000"
+```
+
+---
+
+### getPositionData
+
+Fetches the full position data for a user at a specific market round index.
+
+#### Method Signature
+
+```ts
+getPositionData(
+  userAddress: `0x${string}`,
+  index: number
+): Promise<PositionData>
+```
+
+#### Parameters
+
+| Parameter     | Type                | Required | Description             |
+| ------------- | ------------------- | -------- | ----------------------- |
+| `userAddress` | `` `0x${string}` `` | ✅       | User's Ethereum address |
+| `index`       | `number`            | ✅       | Market round index      |
+
+#### Returns
+
+An object with the following fields (all numeric values are strings):
+
+| Field                   | Type       | Description                               |
+| ----------------------- | ---------- | ----------------------------------------- |
+| `marketType`            | `string`   | Market type identifier                    |
+| `id`                    | `string`   | Position ID (bytes32)                     |
+| `user`                  | `string`   | User's address                            |
+| `amount`                | `string`   | Position amount placed                    |
+| `line`                  | `string`   | Cashout line target                       |
+| `iterations`            | `string`   | Number of RNG iterations required         |
+| `startBlock`            | `string`   | Block number when position was opened     |
+| `startTime`             | `string`   | Unix timestamp when position was opened   |
+| `expiryTime`            | `string`   | Unix timestamp when position expires      |
+| `requiredConfirmations` | `string`   | Number of confirmations required          |
+| `requestIds`            | `string[]` | Array of VRF request IDs                  |
+| `extraData`             | `string`   | Additional encoded position data          |
+
+#### Example
+
+```ts
+const positionData = await market.getPositionData(
+  "0xa682C9022871881b3257A72E103B50fC75013245",
+  1363
+);
+console.log(positionData.amount);    // "9500000"
+console.log(positionData.startTime); // "1767267308"
+console.log(positionData.line);      // "150"
+```
+
+---
+
+### getPositionProgress
+
+Fetches the current settlement progress for a user's position at a specific market round index.
+
+#### Method Signature
+
+```ts
+getPositionProgress(
+  userAddress: `0x${string}`,
+  index: number
+): Promise<PositionProgress>
+```
+
+#### Parameters
+
+| Parameter     | Type                | Required | Description             |
+| ------------- | ------------------- | -------- | ----------------------- |
+| `userAddress` | `` `0x${string}` `` | ✅       | User's Ethereum address |
+| `index`       | `number`            | ✅       | Market round index      |
+
+#### Returns
+
+An object with the following fields:
+
+| Field                   | Type     | Description                                        |
+| ----------------------- | -------- | -------------------------------------------------- |
+| `marketType`            | `string` | Market type identifier                             |
+| `id`                    | `string` | Position ID (bytes32)                              |
+| `user`                  | `string` | User's address                                     |
+| `settlement`            | `string` | Settled payout amount                              |
+| `receivedConfirmations` | `string` | Number of RNG confirmations received so far        |
+| `extraData`             | `string` | Additional encoded progress data                   |
+
+#### Example
+
+```ts
+const progress = await market.getPositionProgress(
+  "0xa682C9022871881b3257A72E103B50fC75013245",
+  1363
+);
+console.log(progress.receivedConfirmations); // "2"
+console.log(progress.settlement);            // "0"
+```
+
+---
+
+### isUserPositionOpen
+
+Checks whether a user has an open position in a specific market round, and returns its amount and confirmation status.
+
+#### Method Signature
+
+```ts
+isUserPositionOpen(
+  user_address: `0x${string}`,
+  index: number
+): Promise<UserPositionInfo>
+```
+
+#### Parameters
+
+| Parameter      | Type                | Required | Description             |
+| -------------- | ------------------- | -------- | ----------------------- |
+| `user_address` | `` `0x${string}` `` | ✅       | User's Ethereum address |
+| `index`        | `number`            | ✅       | Market round index      |
+
+#### Returns
+
+`UserPositionInfo`:
+
+| Field    | Type     | Description                                      |
+| -------- | -------- | ------------------------------------------------ |
+| `amount` | `string` | Position amount placed by the user               |
+| `status` | `string` | Number of RNG confirmations received (`receivedConfirmations`) |
+
+#### Example
+
+```ts
+const position = await market.isUserPositionOpen(
+  "0xa682C9022871881b3257A72E103B50fC75013245",
+  1363
+);
+console.log(position.amount); // "9500000"
+console.log(position.status); // "1"
+```
+
+---
+
+## Write Methods
+
+Write methods return **encoded transaction calldata** as an array of `EncodedCall` objects. They **do not execute transactions** — you must send them through your own provider or smart account client.
+
+### Return Type (All Write Methods)
+
+```ts
+interface EncodedCall {
+  to: `0x${string}`;
+  data: `0x${string}`;
+}
+```
+
+All write methods return `Promise<EncodedCall[]>`.
+
+---
+
+### openMarketMethod
+
+Builds encoded calldata for opening a position in the current market round. Internally fetches the current round index and retrieves RNG data from the API before encoding the transaction.
+
+#### Method Signature
+
+```ts
+openMarketMethod(params: {
+  amount: string;
+  smartAccount: string;
+}): Promise<EncodedCall[]>
+```
+
+#### Parameters
+
+| Parameter      | Type     | Required | Description                              |
+| -------------- | -------- | -------- | ---------------------------------------- |
+| `amount`       | `string` | ✅       | Amount (in USDT) to place as a position  |
+| `smartAccount` | `string` | ✅       | Smart account address                    |
+
+#### Example
+
+```ts
+const calls = await market.openMarketMethod({
+  amount: "10",
+  smartAccount: "0xa682C9022871881b3257A72E103B50fC75013245",
+});
+
+// Execute via your smart account client
+await smartAccountClient.sendTransaction({ calls });
+```
+
+---
+
+### cashOutMethod
+
+Builds encoded calldata for cashing out (closing) an open position. Internally calls the API to retrieve a signed key before encoding the transaction.
+
+#### Method Signature
+
+```ts
+cashOutMethod(params: {
+  smartAccount: string;
+}): Promise<EncodedCall[]>
+```
+
+#### Parameters
+
+| Parameter      | Type     | Required | Description           |
+| -------------- | -------- | -------- | --------------------- |
+| `smartAccount` | `string` | ✅       | Smart account address |
+
+#### Example
+
+```ts
+const calls = await market.cashOutMethod({
+  smartAccount: "0xa682C9022871881b3257A72E103B50fC75013245",
+});
+
+// Execute via your smart account client
+await smartAccountClient.sendTransaction({ calls });
+```
+
+---
+
+## Recommended Usage Pattern
+
+```ts
+import { Market } from "riskmarket-sdk";
+
+const market = new Market({ environment: "production" });
+
+// 1. Read current round info
+const currentIndex = await market.getMarketIndexTermination();
+const round = await market.getMarketRoundByIndex(Number(currentIndex));
+console.log("Current round state:", round.marketState);
+
+// 2. Check if user already has a position
+const position = await market.isUserPositionOpen(
+  "0xYourSmartAccount...",
+  Number(currentIndex)
+);
+
+// 3. Open a position (if none exists)
+if (position.amount === "0") {
+  const openCalls = await market.openMarketMethod({
+    amount: "10",
+    smartAccount: "0xYourSmartAccount...",
+  });
+  await smartAccountClient.sendTransaction({ calls: openCalls });
+}
+
+// 4. Cash out when ready
+const cashOutCalls = await market.cashOutMethod({
+  smartAccount: "0xYourSmartAccount...",
+});
+await smartAccountClient.sendTransaction({ calls: cashOutCalls });
+```
+
+---
+
+## Local Development Setup
+
+To use this SDK locally during development:
+
+1. Navigate to the SDK directory and link it:
+
+   ```bash
+   cd riskmarket-sdk
+   yarn build
+   yarn link
+   ```
+
+2. In your consumer application directory, link to the local SDK:
+
+   ```bash
+   cd /path/to/your/consumer/app
+   yarn link "riskmarket-sdk"
+   ```
+
+3. After making changes to the SDK, rebuild it:
+
+   ```bash
+   yarn build
+   ```
+
+4. Restart your consumer application to pick up the changes.
+
+---
+
+## Versioning Policy
+
+RiskMarket SDK follows **Semantic Versioning**:
+
+- **Patch** (`1.0.x`) → Bug fixes
+- **Minor** (`1.x.0`) → New features, backward compatible
+- **Major** (`x.0.0`) → Breaking API changes
+
+---
+
+**RiskMarket SDK** is built to scale with both products and protocols.

package/dist/Graphs/fetchGraphChartsData.d.ts

@@ -0,0 +1 @@
+export declare const fetchGraphChartsData: () => Promise<any>;

package/dist/Graphs/fetchGraphChartsData.js

@@ -0,0 +1,20 @@
+import AxiosGraphInstance from "../utils/AxiosGraphInstance.js";
+export const fetchGraphChartsData = async () => {
+    const query = `
+    query finalizeMarketTerminations {
+      finalizeMarketTerminations(first: 1000, orderBy: blockNumber, orderDirection: desc) {
+        transactionHash
+        marketIndexTermination
+        random
+      }
+    }
+  `;
+    try {
+        const data = await AxiosGraphInstance(query);
+        return data?.finalizeMarketTerminations ?? [];
+    }
+    catch (error) {
+        console.error("Failed to fetch graph charts data:", error);
+        throw error;
+    }
+};

package/dist/Graphs/fetchOwnerBetHistory.d.ts

@@ -0,0 +1,2 @@
+import { TimePeriod } from "../types.js";
+export declare const fetchOwnerBetHistory: (userAddress: `0x${string}`, timePeriod?: TimePeriod) => Promise<any>;

package/dist/Graphs/fetchOwnerBetHistory.js

@@ -0,0 +1,121 @@
+import AxiosGraphInstance from "../utils/AxiosGraphInstance.js";
+import { UtilitiyFunctions } from "../utils/helpers.js";
+export const fetchOwnerBetHistory = async (userAddress, timePeriod = "all") => {
+    const closePositionQuery = `
+    query closePositionTerminations {
+      closePositionTerminations(where: { user: "${userAddress}" }) {
+        marketIndexTermination
+        positionId
+        settlement
+        closePositionTimeMs
+        blockTimestamp
+        blockNumber
+        id
+        timeElapsed
+        transactionHash
+        user
+      }
+    }
+  `;
+    const openPositionQuery = `
+    query openPositionTerminations {
+      openPositionTerminations(where: { user: "${userAddress}" }) {
+        marketIndexTermination
+        amount
+        blockTimestamp
+        transactionHash
+        blockNumber
+        user
+        positionId
+      }
+    }
+  `;
+    try {
+        const [closePositionData, openPositionData] = await Promise.all([
+            AxiosGraphInstance(closePositionQuery),
+            AxiosGraphInstance(openPositionQuery),
+        ]);
+        let closePositions = closePositionData?.closePositionTerminations ?? [];
+        let openPositions = openPositionData?.openPositionTerminations ?? [];
+        const now = Math.floor(Date.now() / 1000);
+        let timeThreshold = 0;
+        switch (timePeriod) {
+            case "day":
+                timeThreshold = now - 24 * 60 * 60;
+                break;
+            case "week":
+                timeThreshold = now - 7 * 24 * 60 * 60;
+                break;
+            case "month":
+                timeThreshold = now - 30 * 24 * 60 * 60;
+                break;
+            case "all":
+            default:
+                timeThreshold = 0;
+                break;
+        }
+        if (timePeriod !== "all") {
+            closePositions = closePositions.filter((pos) => Number(pos.blockTimestamp) >= timeThreshold);
+            openPositions = openPositions.filter((pos) => Number(pos.blockTimestamp) >= timeThreshold);
+        }
+        const totalAmountFromPlaced = openPositions.reduce((sum, bet) => {
+            return (sum +
+                parseFloat(UtilitiyFunctions.convertFromWei(bet?.amount || "0", "mwei")));
+        }, 0);
+        const totalAmountFromResolved = closePositions.reduce((sum, bet) => {
+            return (sum +
+                parseFloat(UtilitiyFunctions.convertFromWei(bet?.settlement || "0", "mwei")));
+        }, 0);
+        const netProfit = totalAmountFromResolved - totalAmountFromPlaced;
+        const graphData = closePositions.map((closePos) => {
+            const openPos = openPositions.find((op) => op.positionId === closePos.positionId);
+            const amountPlaced = openPos
+                ? parseFloat(UtilitiyFunctions.convertFromWei(openPos.amount || "0", "mwei"))
+                : 0;
+            const settlement = parseFloat(UtilitiyFunctions.convertFromWei(closePos.settlement || "0", "mwei"));
+            const pnl = settlement - amountPlaced;
+            const timestamp = new Date(Number(closePos.blockTimestamp) * 1000).toISOString();
+            const date = new Date(Number(closePos.blockTimestamp) * 1000);
+            let label = "";
+            switch (timePeriod) {
+                case "day": {
+                    const hours = date.getHours().toString().padStart(2, "0");
+                    const minutes = date.getMinutes().toString().padStart(2, "0");
+                    label = `${hours}:${minutes}`;
+                    break;
+                }
+                case "week":
+                case "month":
+                case "all":
+                default: {
+                    const day = date.getDate().toString().padStart(2, "0");
+                    const month = (date.getMonth() + 1).toString().padStart(2, "0");
+                    label = `${day}/${month}`;
+                    break;
+                }
+            }
+            return {
+                label,
+                pnl,
+                timestamp,
+                blockTimestamp: Number(closePos.blockTimestamp),
+            };
+        });
+        const sortedGraphData = graphData.sort((a, b) => a.blockTimestamp - b.blockTimestamp);
+        let cumulativePnl = 0;
+        const graphDataWithOverallPnl = sortedGraphData.map((item) => {
+            cumulativePnl += item.pnl;
+            return {
+                label: item.label,
+                pnl: item.pnl,
+                overallPnl: cumulativePnl,
+                timestamp: item.timestamp,
+            };
+        });
+        return { netProfit, graphData: graphDataWithOverallPnl };
+    }
+    catch (error) {
+        console.error("Failed to fetch owner bet history:", error);
+        throw error;
+    }
+};

package/dist/Graphs/fetchPlayerBetHistory.d.ts

@@ -0,0 +1 @@
+export declare const fetchPlayerBetHistory: (userAddress: `0x${string}`) => Promise<any>;

package/dist/Graphs/fetchPlayerBetHistory.js

@@ -0,0 +1,26 @@
+import AxiosGraphInstance from "../utils/AxiosGraphInstance.js";
+export const fetchPlayerBetHistory = async (userAddress) => {
+    const query = `
+    query openPositionTerminations {
+      openPositionTerminations(where: { user: "${userAddress}" }) {
+        marketIndexTermination
+        amount
+        blockTimestamp
+        transactionHash
+        blockNumber
+        user
+        positionId
+      }
+    }
+  `;
+    try {
+        const data = await AxiosGraphInstance(query);
+        const allPositions = data?.openPositionTerminations ?? [];
+        const sortedHistory = allPositions.sort((a, b) => Number(b.blockTimestamp) - Number(a.blockTimestamp));
+        return sortedHistory;
+    }
+    catch (error) {
+        console.error("Failed to fetch player bet history:", error);
+        throw error;
+    }
+};

package/dist/Graphs/fetchPlayerBetHistoryInEpochs.d.ts

@@ -0,0 +1 @@
+export declare const fetchPlayerBetHistoryInEpochs: (userAddress: `0x${string}`) => Promise<any>;

package/dist/Graphs/fetchPlayerBetHistoryInEpochs.js

@@ -0,0 +1,29 @@
+import AxiosGraphInstance from "../utils/AxiosGraphInstance.js";
+export const fetchPlayerBetHistoryInEpochs = async (userAddress) => {
+    const currentEpoch = Date.now() / 1000;
+    const currentDate = new Date(currentEpoch * 1000);
+    const startOfDay = new Date(currentDate.getFullYear(), currentDate.getMonth(), currentDate.getDate());
+    const startOfDayEpoch = Math.floor(startOfDay.getTime() / 1000);
+    const endOfDayEpoch = startOfDayEpoch + 86399;
+    const query = `
+    query openPositionTerminations {
+      openPositionTerminations(where: {
+        user: "${userAddress}",
+        blockTimestamp_gte: "${startOfDayEpoch}",
+        blockTimestamp_lte: "${endOfDayEpoch}"
+      }) {
+        amount
+      }
+    }
+  `;
+    try {
+        const data = await AxiosGraphInstance(query);
+        const allPositions = data?.openPositionTerminations ?? [];
+        const sortedHistory = allPositions.sort((a, b) => Number(b.blockTimestamp) - Number(a.blockTimestamp));
+        return sortedHistory;
+    }
+    catch (error) {
+        console.error("Failed to fetch player bet history:", error);
+        throw error;
+    }
+};

package/dist/Graphs/fetchPlayerHistory.d.ts

@@ -0,0 +1 @@
+export declare const fetchPlayerHistory: (userAddress: `0x${string}`) => Promise<any>;

package/dist/Graphs/fetchPlayerHistory.js

@@ -0,0 +1,29 @@
+import AxiosGraphInstance from "../utils/AxiosGraphInstance.js";
+export const fetchPlayerHistory = async (userAddress) => {
+    const query = `
+    query closePositionTerminations {
+      closePositionTerminations(where: { user: "${userAddress}" }) {
+        marketIndexTermination
+        positionId
+        settlement
+        closePositionTimeMs
+        blockTimestamp
+        blockNumber
+        id
+        timeElapsed
+        transactionHash
+        user
+      }
+    }
+  `;
+    try {
+        const data = await AxiosGraphInstance(query);
+        const allPositions = data?.closePositionTerminations ?? [];
+        const sortedHistory = allPositions.sort((a, b) => Number(b.blockTimestamp) - Number(a.blockTimestamp));
+        return sortedHistory;
+    }
+    catch (error) {
+        console.error("Failed to fetch player history:", error);
+        throw error;
+    }
+};

package/dist/Graphs.d.ts

@@ -0,0 +1,14 @@
+import { type Environment } from "./constants/index.js";
+import { TimePeriod } from "./types.js";
+export interface GraphOptions {
+    environment?: Environment;
+}
+export declare class Graphs {
+    private config;
+    constructor(options?: GraphOptions);
+    fetchGraphChartsData(): Promise<any>;
+    fetchOwnerBetHistory(userAddress: `0x${string}`, timePeriod?: TimePeriod): Promise<any>;
+    fetchPlayerBetHistory(userAddress: `0x${string}`): Promise<any>;
+    fetchPlayerBetHistoryInEpochs(userAddress: `0x${string}`): Promise<any>;
+    fetchPlayerHistory(userAddress: `0x${string}`): Promise<any>;
+}