@the-situation/starknet

Starknet contract wrappers for The Situation AMM, factory, and math runtime contracts. Provides type-safe read and write access to on-chain prediction markets.

Install

npm install @the-situation/starknet

Peer dependency: starknet (v9+).

Main Classes

AMMContract

Wraps a deployed normal-distribution AMM market. Extends BaseContract.

View methods:

| Method | Returns | Description | |--------|---------|-------------| | getDistribution() | NormalDistribution \| LognormalDistribution \| BivariateNormalDistribution | Current market distribution (auto-detects type from ABI) | | getParams() | AmmParams | Market parameters (k, backing, tolerance) | | getMarketStatus() | MarketStatus | Initialization, pause, and settlement state | | getConfig() | AmmConfig | Full config including collateral token and decimals | | getLPInfo() | LPInfo | Total LP shares and total backing deposited | | getLPShares(address) | SQ128x128 | LP share balance for an address | | getPosition(trader) | Position | Trader's distribution and locked collateral | | getPositionSummary(trader) | PositionSummary | Collateral, flags (exists, claimed) | | getPositionCompact(trader) | PositionCompact | Original and effective distributions, full flags | | getFeeConfig() | FeeConfig | LP, protocol, and settlement fee basis points | | getOriginalDistribution(trader) | { mean, variance, sigma } | Distribution when trader first entered | | checkSellPosition(trader, params) | PositionSellResult | Dry-run sell validation |

Transaction builders (return Call objects for multicall batching):

| Method | Description | |--------|-------------| | buildExecuteTrade(params) | Trade to a new distribution | | buildAddLiquidity(shares) | Deposit LP liquidity | | buildRemoveLiquidity(shares) | Withdraw LP liquidity | | buildClaim() | Claim settlement payout | | buildClaimFor(trader) | Claim on behalf of another address | | buildSellPositionGuarded(params, guards) | Sell position with stale-state guards | | buildSettle(value) | Settle the market (admin) | | buildPause() / buildUnpause() | Pause/unpause trading (admin) |

FactoryContract

Deploys new markets. Supports four distribution types:

• buildDeployNormalMarket(params)
• buildDeployLognormalMarket(params)
• buildDeployBivariateNormalMarket(params)
• buildDeployMultinoulliMarket(params)

Each takes a profile ID, salt, metadata hash, initial distribution, and computation hints.

MathLibraryContract / NormalMathRuntimeContract

Stateless math runtime for off-chain computation previews: trade validation (checkTradeView), position valuation, claim computation, liquidity previews, and hint generation (computeHints). MathLibraryContract is a deprecated alias for NormalMathRuntimeContract.

MultinoulliAMMContract

Wraps categorical/multinoulli markets with similar view and trade methods adapted for discrete probability distributions.

SQ128x128

All on-chain numeric values (means, variances, collateral amounts) use SQ128x128, a signed 128.128 fixed-point type from @the-situation/core. The contract wrappers handle conversion automatically:

• Reading: Raw 4-limb values from Starknet are parsed into SQ128x128 objects. Call .toNumber() to get a JS number.
• Writing: Pass SQ128x128Raw objects ({ limb0, limb1, limb2, limb3, neg }) to transaction builders. Use SQ128x128.fromNumber(n) to create them.

Providers

import { createProvider, createAccount, getNetworkConfig } from '@the-situation/starknet';

// Read-only provider
const provider = createProvider({ network: 'mainnet' });

// Account for transactions
const account = createAccount({
  address: '0x...',
  privateKey: '0x...',
  provider,
});

Available networks: mainnet, sepolia.

Usage Example

import { AMMContract } from '@the-situation/starknet';
import { createProvider } from '@the-situation/starknet';
import ammAbi from './abi/amm.json';

const provider = createProvider({ network: 'mainnet' });

const amm = new AMMContract({
  address: '0x123...',
  abi: ammAbi,
  provider,
});

// Read the current distribution
const dist = await amm.getDistribution();
if (dist && 'mean' in dist) {
  console.log('Mean:', dist.mean.toNumber());
  console.log('Sigma:', dist.sigma.toNumber());
}

// Check LP shares
const shares = await amm.getLPShares('0xMyAddress...');
console.log('LP shares:', shares?.toNumber());

// Get LP pool info
const lpInfo = await amm.getLPInfo();
console.log('Total backing:', lpInfo?.totalBackingDeposited.toNumber());

// Build a trade (returns a Call for multicall)
const tradeCall = amm.buildExecuteTrade({
  candidateMean: targetMean,
  candidateVariance: targetVariance,
  candidateSigma: targetSigma,
  xStar: xStarRaw,
  suppliedCollateral: collateralRaw,
  hints: hintsRaw,
});

// Execute via starknet.js account
await account.execute([approveCall, tradeCall]);

License

MIT