@make-software/cspr-trade-mcp-sdk 0.1.0

package/src/resolver/token-resolver.ts

@@ -0,0 +1,43 @@
+import type { Token } from '../types/index.js';
+
+export class TokenResolver {
+  private cache: Token[] | null = null;
+  private cacheTimestamp = 0;
+  private readonly cacheTtlMs = 30_000; // 30 seconds
+
+  constructor(private readonly fetchTokens: () => Promise<Token[]>) {}
+
+  async resolve(identifier: string): Promise<Token> {
+    const tokens = await this.getTokens();
+    const id = identifier.trim();
+
+    // 1. Match by symbol (case-insensitive)
+    const bySymbol = tokens.find(t => t.symbol.toLowerCase() === id.toLowerCase());
+    if (bySymbol) return bySymbol;
+
+    // 2. Match by contract package hash
+    const byHash = tokens.find(t => t.packageHash.toLowerCase() === id.toLowerCase());
+    if (byHash) return byHash;
+
+    // 3. Match by name (case-insensitive)
+    const byName = tokens.find(t => t.name.toLowerCase() === id.toLowerCase());
+    if (byName) return byName;
+
+    throw new Error(`Token not found: "${identifier}". Use a token symbol (e.g., "CSPR"), name, or contract package hash.`);
+  }
+
+  async getTokens(): Promise<Token[]> {
+    const now = Date.now();
+    if (this.cache && now - this.cacheTimestamp < this.cacheTtlMs) {
+      return this.cache;
+    }
+    this.cache = await this.fetchTokens();
+    this.cacheTimestamp = now;
+    return this.cache;
+  }
+
+  invalidateCache(): void {
+    this.cache = null;
+    this.cacheTimestamp = 0;
+  }
+}

package/src/transactions/approve.ts

@@ -0,0 +1,14 @@
+import casperSdk from 'casper-js-sdk';
+const { Args, CLValue, Key } = casperSdk;
+
+export interface ApproveArgsParams {
+  spenderPackageHash: string;
+  amount: string;
+}
+
+export function buildApproveArgs(params: ApproveArgsParams): Args {
+  return Args.fromMap({
+    spender: CLValue.newCLKey(Key.newKey(params.spenderPackageHash)),
+    amount: CLValue.newCLUInt256(params.amount),
+  });
+}

package/src/transactions/index.ts

@@ -0,0 +1,5 @@
+export { buildProxyWasmArgs, serializeInnerArgs } from './proxy-wasm.js';
+export { getSwapEntryPoint, buildSwapInnerArgs, getSwapAttachedValue } from './swap.js';
+export { buildAddLiquidityInnerArgs, buildRemoveLiquidityInnerArgs } from './liquidity.js';
+export { buildApproveArgs } from './approve.js';
+export { buildWasmTransaction, buildContractCallTransaction } from './transaction-builder.js';

package/src/transactions/liquidity.ts

@@ -0,0 +1,92 @@
+import casperSdk from 'casper-js-sdk';
+const { Args, CLValue, Key } = casperSdk;
+
+export type AddLiquidityInnerArgsParams =
+  | {
+      isCSPRPair: false;
+      tokenAHash: string;
+      tokenBHash: string;
+      amountADesired: string;
+      amountBDesired: string;
+      amountAMin: string;
+      amountBMin: string;
+      accountHash: string;
+      deadline: number;
+    }
+  | {
+      isCSPRPair: true;
+      tokenHash: string;
+      amountTokenDesired: string;
+      amountTokenMin: string;
+      amountCSPRMin: string;
+      accountHash: string;
+      deadline: number;
+    };
+
+export function buildAddLiquidityInnerArgs(params: AddLiquidityInnerArgsParams): Args {
+  if (params.isCSPRPair) {
+    return Args.fromMap({
+      token: CLValue.newCLKey(Key.newKey(params.tokenHash)),
+      amount_token_desired: CLValue.newCLUInt256(params.amountTokenDesired),
+      amount_token_min: CLValue.newCLUInt256(params.amountTokenMin),
+      amount_cspr_min: CLValue.newCLUInt256(params.amountCSPRMin),
+      to: CLValue.newCLKey(Key.newKey(params.accountHash)),
+      deadline: CLValue.newCLUint64(params.deadline),
+    });
+  }
+
+  return Args.fromMap({
+    token_a: CLValue.newCLKey(Key.newKey(params.tokenAHash)),
+    token_b: CLValue.newCLKey(Key.newKey(params.tokenBHash)),
+    amount_a_desired: CLValue.newCLUInt256(params.amountADesired),
+    amount_b_desired: CLValue.newCLUInt256(params.amountBDesired),
+    amount_a_min: CLValue.newCLUInt256(params.amountAMin),
+    amount_b_min: CLValue.newCLUInt256(params.amountBMin),
+    to: CLValue.newCLKey(Key.newKey(params.accountHash)),
+    deadline: CLValue.newCLUint64(params.deadline),
+  });
+}
+
+export type RemoveLiquidityInnerArgsParams =
+  | {
+      isCSPRPair: false;
+      tokenAHash: string;
+      tokenBHash: string;
+      liquidity: string;
+      amountAMin: string;
+      amountBMin: string;
+      accountHash: string;
+      deadline: number;
+    }
+  | {
+      isCSPRPair: true;
+      tokenHash: string;
+      liquidity: string;
+      amountTokenMin: string;
+      amountCSPRMin: string;
+      accountHash: string;
+      deadline: number;
+    };
+
+export function buildRemoveLiquidityInnerArgs(params: RemoveLiquidityInnerArgsParams): Args {
+  if (params.isCSPRPair) {
+    return Args.fromMap({
+      token: CLValue.newCLKey(Key.newKey(params.tokenHash)),
+      liquidity: CLValue.newCLUInt256(params.liquidity),
+      amount_token_min: CLValue.newCLUInt256(params.amountTokenMin),
+      amount_cspr_min: CLValue.newCLUInt256(params.amountCSPRMin),
+      to: CLValue.newCLKey(Key.newKey(params.accountHash)),
+      deadline: CLValue.newCLUint64(params.deadline),
+    });
+  }
+
+  return Args.fromMap({
+    token_a: CLValue.newCLKey(Key.newKey(params.tokenAHash)),
+    token_b: CLValue.newCLKey(Key.newKey(params.tokenBHash)),
+    liquidity: CLValue.newCLUInt256(params.liquidity),
+    amount_a_min: CLValue.newCLUInt256(params.amountAMin),
+    amount_b_min: CLValue.newCLUInt256(params.amountBMin),
+    to: CLValue.newCLKey(Key.newKey(params.accountHash)),
+    deadline: CLValue.newCLUint64(params.deadline),
+  });
+}

package/src/transactions/proxy-wasm.ts

@@ -0,0 +1,33 @@
+import { hexToBytes } from '@noble/hashes/utils';
+import casperSdk from 'casper-js-sdk';
+const { Args, CLTypeUInt8, CLValue } = casperSdk;
+
+export interface ProxyWasmArgsParams {
+  routerPackageHash: string;  // hex without 'hash-' prefix
+  entryPoint: string;
+  innerArgs: Args;
+  attachedValue: string;       // motes as string
+}
+
+export function serializeInnerArgs(args: Args): Uint8Array {
+  return args.toBytes();
+}
+
+export function buildProxyWasmArgs(params: ProxyWasmArgsParams): Args {
+  const { routerPackageHash, entryPoint, innerArgs, attachedValue } = params;
+
+  const rawArgsBytes = serializeInnerArgs(innerArgs);
+
+  const argsBytes: CLValue[] = [];
+  for (let i = 0; i < rawArgsBytes.length; i++) {
+    argsBytes.push(CLValue.newCLUint8(rawArgsBytes[i]));
+  }
+
+  return Args.fromMap({
+    package_hash: CLValue.newCLByteArray(hexToBytes(routerPackageHash)),
+    entry_point: CLValue.newCLString(entryPoint),
+    args: CLValue.newCLList(CLTypeUInt8, argsBytes),
+    attached_value: CLValue.newCLUInt512(attachedValue),
+    amount: CLValue.newCLUInt512(attachedValue),
+  });
+}

package/src/transactions/swap.ts

@@ -0,0 +1,76 @@
+import casperSdk from 'casper-js-sdk';
+const { Args, CLTypeKey, CLValue, Key } = casperSdk;
+import type { QuoteType } from '../types/index.js';
+
+export function getSwapEntryPoint(
+  isFirstTokenNative: boolean,
+  isSecondTokenNative: boolean,
+  quoteType: QuoteType,
+): string {
+  if (isFirstTokenNative) {
+    return quoteType === 'exact_in' ? 'swap_exact_cspr_for_tokens' : 'swap_cspr_for_exact_tokens';
+  }
+  if (isSecondTokenNative) {
+    return quoteType === 'exact_in' ? 'swap_exact_tokens_for_cspr' : 'swap_tokens_for_exact_cspr';
+  }
+  return quoteType === 'exact_in' ? 'swap_exact_tokens_for_tokens' : 'swap_tokens_for_exact_tokens';
+}
+
+export interface SwapInnerArgsParams {
+  isFirstTokenNative: boolean;
+  isSecondTokenNative: boolean;
+  quoteType: QuoteType;
+  path: string[];
+  accountHash: string;
+  deadline: number;
+  amountIn: string;
+  amountOut: string;
+  amountInMax: string;
+  amountOutMin: string;
+}
+
+export function buildSwapInnerArgs(params: SwapInnerArgsParams): Args {
+  const {
+    isFirstTokenNative, isSecondTokenNative, quoteType,
+    path, accountHash, deadline,
+    amountIn, amountOut, amountInMax, amountOutMin,
+  } = params;
+
+  const isBothNotNative = !isFirstTokenNative && !isSecondTokenNative;
+
+  const argsMap: Record<string, CLValue> = {
+    path: CLValue.newCLList(
+      CLTypeKey,
+      path.map(hash => CLValue.newCLKey(Key.newKey(hash))),
+    ),
+    to: CLValue.newCLKey(Key.newKey(accountHash)),
+    deadline: CLValue.newCLUint64(deadline),
+  };
+
+  if (isFirstTokenNative && quoteType === 'exact_in') {
+    argsMap.amount_out_min = CLValue.newCLUInt256(amountOutMin);
+  }
+  if (isFirstTokenNative && quoteType === 'exact_out') {
+    argsMap.amount_out = CLValue.newCLUInt256(amountOut);
+  }
+  if ((isSecondTokenNative || isBothNotNative) && quoteType === 'exact_in') {
+    argsMap.amount_in = CLValue.newCLUInt256(amountIn);
+    argsMap.amount_out_min = CLValue.newCLUInt256(amountOutMin);
+  }
+  if ((isSecondTokenNative || isBothNotNative) && quoteType === 'exact_out') {
+    argsMap.amount_in_max = CLValue.newCLUInt256(amountInMax);
+    argsMap.amount_out = CLValue.newCLUInt256(amountOut);
+  }
+
+  return Args.fromMap(argsMap);
+}
+
+export function getSwapAttachedValue(params: {
+  isFirstTokenNative: boolean;
+  quoteType: QuoteType;
+  amountIn: string;
+  amountInMax: string;
+}): string {
+  if (!params.isFirstTokenNative) return '0';
+  return params.quoteType === 'exact_in' ? params.amountIn : params.amountInMax;
+}

package/src/transactions/transaction-builder.ts

@@ -0,0 +1,44 @@
+import casperSdk from 'casper-js-sdk';
+import type { Args, Transaction } from 'casper-js-sdk';
+const { SessionBuilder, ContractCallBuilder, PublicKey } = casperSdk;
+import type { NetworkConfig } from '../config.js';
+
+export function buildWasmTransaction(params: {
+  publicKey: string;
+  paymentAmount: string;
+  wasmBinary: Uint8Array;
+  runtimeArgs: Args;
+  networkConfig: NetworkConfig;
+}): Transaction {
+  const { publicKey, paymentAmount, wasmBinary, runtimeArgs, networkConfig } = params;
+  return new SessionBuilder()
+    .from(PublicKey.fromHex(publicKey))
+    .wasm(wasmBinary)
+    .installOrUpgrade()
+    .runtimeArgs(runtimeArgs)
+    .chainName(networkConfig.chainName)
+    .payment(Number(paymentAmount))
+    .ttl(networkConfig.ttl)
+    .build();
+}
+
+export function buildContractCallTransaction(params: {
+  publicKey: string;
+  paymentAmount: string;
+  contractPackageHash: string;
+  entryPoint: string;
+  runtimeArgs: Args;
+  networkConfig: NetworkConfig;
+}): Transaction {
+  const { publicKey, paymentAmount, contractPackageHash, entryPoint, runtimeArgs, networkConfig } = params;
+  const hash = contractPackageHash.replace('hash-', '');
+  return new ContractCallBuilder()
+    .from(PublicKey.fromHex(publicKey))
+    .byPackageHash(hash)
+    .entryPoint(entryPoint)
+    .runtimeArgs(runtimeArgs)
+    .chainName(networkConfig.chainName)
+    .payment(Number(paymentAmount))
+    .ttl(networkConfig.ttl)
+    .build();
+}

package/src/types/api.ts

@@ -0,0 +1,32 @@
+/** Generic API success response */
+export interface ApiResponse<T> {
+  data: T;
+  message?: string;
+  status?: string;
+}
+
+/** Paginated API response */
+export interface PaginatedApiResponse<T> {
+  data: T[];
+  item_count: number;
+  page_count: number;
+}
+
+/** API error */
+export interface ApiError {
+  code: number;
+  message: string;
+  status?: number;
+}
+
+/** Pagination options */
+export interface PaginationOptions {
+  page?: number;
+  page_size?: number;
+}
+
+/** Sort options */
+export interface SortOptions {
+  order_by?: string;
+  order_direction?: 'asc' | 'desc';
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './api.js';
+export * from './token.js';
+export * from './pair.js';
+export * from './quote.js';
+export * from './liquidity.js';
+export * from './transaction.js';

package/src/types/liquidity.ts

@@ -0,0 +1,72 @@
+import type { PairApiResponse } from './pair.js';
+
+/** Liquidity position API response */
+export interface LiquidityPositionApiResponse {
+  account_hash: string;
+  pair_contract_package_hash: string;
+  lp_token_balance: string;
+  pair: PairApiResponse;
+  pair_lp_tokens_total_supply: string;
+}
+
+/** Liquidity position for SDK consumption */
+export interface LiquidityPosition {
+  accountHash: string;
+  pairContractPackageHash: string;
+  lpTokenBalance: string;
+  lpTokenTotalSupply: string;
+  pair: {
+    token0Symbol: string;
+    token1Symbol: string;
+    token0PackageHash: string;
+    token1PackageHash: string;
+    reserve0: string;
+    reserve1: string;
+    decimals0: number;
+    decimals1: number;
+  };
+  /** User's share of the pool as percentage */
+  poolShare: string;
+  /** Estimated token0 amount based on pool share */
+  estimatedToken0Amount: string;
+  /** Estimated token1 amount based on pool share */
+  estimatedToken1Amount: string;
+}
+
+/** Impermanent loss response */
+export interface ImpermanentLossApiResponse {
+  pair_contract_package_hash: string;
+  account_hash: string;
+  value: string;
+  timestamp: string;
+}
+
+export interface ImpermanentLoss {
+  pairContractPackageHash: string;
+  value: string;
+  timestamp: string;
+}
+
+/** Add liquidity parameters */
+export interface AddLiquidityParams {
+  tokenA: string;              // symbol, name, or hash
+  tokenB: string;              // symbol, name, or hash
+  amountA: string;             // human-readable
+  amountB: string;             // human-readable
+  slippageBps?: number;        // basis points (default 300 = 3%)
+  deadlineMinutes?: number;    // default 20
+  senderPublicKey: string;     // hex public key
+  /** Raw token A balance for approval amount. Falls back to amountA in motes. */
+  tokenABalance?: string;
+  /** Raw token B balance for approval amount. Falls back to amountB in motes. */
+  tokenBBalance?: string;
+}
+
+/** Remove liquidity parameters */
+export interface RemoveLiquidityParams {
+  pairContractPackageHash: string;
+  percentage: number;           // 1-100
+  slippageBps?: number;
+  deadlineMinutes?: number;
+  senderPublicKey: string;
+}

package/src/types/pair.ts

@@ -0,0 +1,29 @@
+import type { ContractPackage } from './token.js';
+
+/** Pair as returned by API */
+export interface PairApiResponse {
+  contract_package_hash: string;
+  token0_contract_package_hash: string;
+  token1_contract_package_hash: string;
+  decimals0: number;
+  decimals1: number;
+  reserve0: string;
+  reserve1: string;
+  timestamp: string;
+  latest_event_id: string;
+  contract_package: ContractPackage;
+  token0_contract_package: ContractPackage;
+  token1_contract_package: ContractPackage;
+}
+
+/** Pair for SDK consumption */
+export interface Pair {
+  contractPackageHash: string;
+  token0: { packageHash: string; symbol: string; name: string; decimals: number; iconUrl: string | null };
+  token1: { packageHash: string; symbol: string; name: string; decimals: number; iconUrl: string | null };
+  reserve0: string;
+  reserve1: string;
+  timestamp: string;
+  fiatPrice0: number | null;
+  fiatPrice1: number | null;
+}

package/src/types/quote.ts

@@ -0,0 +1,41 @@
+/** Quote API response */
+export interface QuoteApiResponse {
+  amount_in: string;
+  amount_out: string;
+  execution_price: string;
+  mid_price: string;
+  path: string[];
+  price_impact: string;
+  recommended_slippage_bps: string;
+  type_id: 1 | 2;
+}
+
+/** Quote type enum */
+export type QuoteType = 'exact_in' | 'exact_out';
+
+/** Quote parameters */
+export interface QuoteParams {
+  tokenIn: string;   // symbol, name, or hash
+  tokenOut: string;   // symbol, name, or hash
+  amount: string;     // human-readable amount
+  type: QuoteType;
+}
+
+/** Resolved quote for SDK consumption */
+export interface Quote {
+  amountIn: string;           // raw amount
+  amountOut: string;          // raw amount
+  amountInFormatted: string;  // human-readable
+  amountOutFormatted: string; // human-readable
+  executionPrice: string;
+  midPrice: string;
+  path: string[];             // contract package hashes
+  pathSymbols: string[];      // token symbols for display
+  priceImpact: string;        // percentage string
+  recommendedSlippageBps: string;
+  type: QuoteType;
+  tokenInSymbol: string;
+  tokenOutSymbol: string;
+  tokenInDecimals: number;
+  tokenOutDecimals: number;
+}

package/src/types/token.ts

@@ -0,0 +1,48 @@
+/** Contract package metadata from CSPR.cloud */
+export interface ContractPackage {
+  contract_package_hash: string;
+  owner_public_key: string;
+  name: string;
+  description: string | null;
+  metadata: TokenMetadata;
+  icon_url: string | null;
+  website_url: string | null;
+  latest_version_contract_hash: string | null;
+  csprtrade_data: { price: number } | null;
+}
+
+export interface TokenMetadata {
+  balances_uref: string;
+  decimals: number;
+  name: string;
+  symbol: string;
+  total_supply_uref: string;
+}
+
+/** Token as returned by GET /tokens */
+export interface TokenApiResponse {
+  contract_package_hash: string;
+  contract_package: ContractPackage;
+  listed_at: string;
+  sorting_order: number;
+  total_value_locked?: string;
+}
+
+/** Resolved token for SDK consumption */
+export interface Token {
+  id: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  packageHash: string;
+  iconUrl: string | null;
+  fiatPrice: number | null;
+}
+
+/** Currency for fiat display */
+export interface Currency {
+  id: number;
+  code: string;
+  name: string;
+  symbol: string;
+}

package/src/types/transaction.ts

@@ -0,0 +1,72 @@
+/** Swap parameters */
+export interface SwapParams {
+  tokenIn: string;             // symbol, name, or hash
+  tokenOut: string;            // symbol, name, or hash
+  amount: string;              // human-readable
+  type: 'exact_in' | 'exact_out';
+  slippageBps?: number;        // basis points (default 300 = 3%)
+  deadlineMinutes?: number;    // default 20
+  senderPublicKey: string;     // hex public key
+  /** Raw token balance for approval amount (matching CSPR.trade pattern). Falls back to swap amount. */
+  tokenInBalance?: string;
+}
+
+/** Token approval parameters */
+export interface ApprovalParams {
+  tokenContractPackageHash: string;
+  spenderPackageHash: string;
+  amount: string;              // raw amount
+  senderPublicKey: string;
+}
+
+/** The result of building a transaction */
+export interface TransactionBundle {
+  /** The unsigned transaction as JSON */
+  transactionJson: string;
+  /** Human-readable description of what this transaction does */
+  summary: string;
+  /** Gas cost in CSPR */
+  estimatedGasCost: string;
+  /** If token approvals are needed first, these contain those transactions (sign & submit each before the main tx) */
+  approvalsRequired?: TransactionBundle[];
+  /** Safety warnings (high price impact, high slippage, etc.) */
+  warnings: string[];
+}
+
+/** Result of submitting a transaction */
+export interface SubmitResult {
+  transactionHash: string;
+}
+
+/** Transaction status */
+export interface TransactionStatus {
+  hash: string;
+  status: 'pending' | 'success' | 'failed' | 'expired';
+  errorMessage?: string;
+}
+
+/** Signer interface for pluggable signing */
+export interface Signer {
+  sign(deployJson: string): Promise<string>;
+}
+
+/** Swap history entry */
+export interface SwapHistoryEntry {
+  transactionHash: string;
+  timestamp: string;
+  token0ContractPackageHash: string;
+  token1ContractPackageHash: string;
+  amount0In: string;
+  amount1In: string;
+  amount0Out: string;
+  amount1Out: string;
+  senderAccountHash: string;
+}
+
+/** Swap history query params */
+export interface SwapHistoryQuery {
+  publicKey?: string;
+  pairContractPackageHash?: string;
+  page?: number;
+  pageSize?: number;
+}

package/src/utils/amounts.ts

@@ -0,0 +1,30 @@
+import Big from 'big.js';
+
+export function toRawAmount(humanAmount: string, decimals: number): string {
+  const big = new Big(humanAmount);
+  const multiplier = new Big(10).pow(decimals);
+  return big.times(multiplier).toFixed(0);
+}
+
+export function toFormattedAmount(rawAmount: string, decimals: number): string {
+  const big = new Big(rawAmount);
+  const divisor = new Big(10).pow(decimals);
+  const result = big.div(divisor);
+  const str = result.toFixed();
+  if (str.includes('.')) {
+    return str.replace(/\.?0+$/, '') || '0';
+  }
+  return str;
+}
+
+export function calculateMinWithSlippage(rawAmount: string, slippageBps: number): string {
+  const amount = new Big(rawAmount);
+  const factor = new Big(1).minus(new Big(slippageBps).div(10000));
+  return amount.times(factor).toFixed(0, Big.roundDown);
+}
+
+export function calculateMaxWithSlippage(rawAmount: string, slippageBps: number): string {
+  const amount = new Big(rawAmount);
+  const factor = new Big(1).plus(new Big(slippageBps).div(10000));
+  return amount.times(factor).toFixed(0, Big.roundUp);
+}