range-bet-math-core

A WebAssembly-powered library that implements the mathematical functions for the Signals Protocol. This package provides cost calculation functions for prediction market betting.

Installation

npm install range-bet-math-core
# or
yarn add range-bet-math-core

API Reference

| Function | Description | Parameters | Return Type | | ---------------------------- | ----------------------------------------- | ----------------------------------------------- | ----------- | | calculateBinBuyCost | Calculate cost to buy tokens in a bin | x: bigint, q: bigint, t: bigint | bigint | | calculateBinSellCost | Calculate revenue from selling tokens | x: bigint, q: bigint, t: bigint | bigint | | calculateMultiBinsBuyCost | Calculate cost for multiple bins | x: bigint, qs: BigUint64Array, t: bigint | bigint | | calculateMultiBinsSellCost | Calculate revenue for multiple bins | x: bigint, qs: BigUint64Array, t: bigint | bigint | | calculateXForMultiBins | Find max tokens purchasable within budget | budget: bigint, qs: BigUint64Array, t: bigint | bigint |

Where:

• x: Amount of tokens to purchase/sell
• q: Current token quantity in the bin
• qs: Array of token quantities in multiple bins
• t: Total token quantity in the market
• budget: Available budget for purchasing tokens

Usage Examples

Basic Cost Calculation

import { calculateBinBuyCost } from "range-bet-math-core";

// Calculate purchase cost
const cost = calculateBinBuyCost(100n, 500n, 1000n);
console.log(`Purchase cost: ${cost}`);

Multiple Bins Calculation

import { calculateMultiBinsBuyCost } from "range-bet-math-core";

// Create bin array using BigUint64Array (required)
const bins = new BigUint64Array([300n, 400n, 500n]);

// Calculate purchase cost across multiple bins
const cost = calculateMultiBinsBuyCost(100n, bins, 1000n);
console.log(`Multiple bins purchase cost: ${cost}`);

Finding Maximum Purchasable Amount

import { calculateXForMultiBins } from "range-bet-math-core";

const budget = 10000n;
const bins = new BigUint64Array([300n, 400n, 500n]);

// Calculate maximum tokens purchasable with budget
const x = calculateXForMultiBins(budget, bins, 1000n);
console.log(`Maximum purchasable: ${x} tokens`);

React Integration Example

import React, { useState, useEffect } from "react";
import { calculateBinBuyCost } from "range-bet-math-core";

function BettingCalculator() {
  const [amount, setAmount] = useState(100);
  const [cost, setCost] = useState<string | null>(null);

  useEffect(() => {
    try {
      const calculatedCost = calculateBinBuyCost(BigInt(amount), 500n, 1000n);
      setCost(calculatedCost.toString());
    } catch (error) {
      console.error("Calculation error:", error);
    }
  }, [amount]);

  return (
    <div>
      <h2>Betting Cost Calculator</h2>
      <input
        type="number"
        value={amount}
        onChange={(e) => setAmount(Number(e.target.value))}
        min="1"
      />
      <div>
        <p>Purchase cost: {cost}</p>
      </div>
    </div>
  );
}

Next.js Integration Example

"use client"; // Important: only use in client components

import { useState, useEffect } from "react";
import { calculateBinBuyCost } from "range-bet-math-core";

export default function BettingComponent() {
  const [cost, setCost] = useState<string | null>(null);

  useEffect(() => {
    try {
      const calculatedCost = calculateBinBuyCost(100n, 500n, 1000n);
      setCost(calculatedCost.toString());
    } catch (error) {
      console.error("Calculation error:", error);
    }
  }, []);

  return (
    <div>
      <h1>Betting Cost</h1>
      {cost ? <p>Purchase cost: {cost}</p> : <p>Calculating...</p>}
    </div>
  );
}

Important Notes

• All functions require BigInt inputs and return BigInt values
• Arrays must be passed as BigUint64Array instances
• This package is for client-side use (browsers); server-side requires additional configuration
• Always implement error handling as invalid inputs will throw errors
• Common error cases: q > t, division by zero, overflow in calculations

Mathematical Background

This library implements the $(q+t)/(T+t)$ integral formula:

$$\int_{t=0}^{x} \frac{q+t}{T+t} , dt = x + (q-T) \ln\left(\frac{T+x}{T}\right)$$

Where:

• $q$: Current token quantity in the bin
• $T$: Total token supply in the market
• $x$: Token quantity to purchase

Note: While the API uses integer values (BigInt), the underlying WASM module performs floating-point calculations internally for accurate logarithmic operations.

For a detailed explanation of the mathematical model:

• Mathematical Model Documentation
• Implementation Details

Additional Documentation

• TypeScript Guide - More detailed usage guide
• Signals Protocol - Main project

License

ISC