@shipload/sdk 0.7.1 → 2.0.0-rc2

package/src/trading/deal.ts

@@ -0,0 +1,207 @@
+import {Int64, UInt16, UInt32, UInt64, UInt64Type} from '@wharfkit/antelope'
+import {Coordinates, GoodPrice, PRECISION, ShipLike} from '../types'
+import {Location} from '../entities/location'
+import {Ship} from '../entities/ship'
+import {
+    distanceBetweenCoordinates,
+    type EstimatedTravelTime,
+    estimateTravelTime,
+} from '../travel/travel'
+import {calculateProfitPerSecond, calculateTradeProfit, isProfitable} from './trade'
+
+/**
+ * Trading deal interface representing a profitable trade opportunity
+ */
+export interface Deal {
+    /** Origin location */
+    origin: Location
+    /** Destination location */
+    destination: Location
+    /** Good to trade */
+    good: GoodPrice
+    /** Distance between origin and destination */
+    distance: UInt64
+    /** Available supply at origin */
+    supply: UInt16
+    /** Buy price at origin */
+    buyPrice: UInt32
+    /** Sell price at destination */
+    sellPrice: UInt32
+    /** Profit per unit */
+    profitPerUnit: UInt32
+    /** Maximum quantity that can be traded */
+    maxQuantity: UInt32
+    /** Total profit for max quantity */
+    totalProfit: Int64
+    /** Estimated travel time in seconds */
+    travelTime: UInt32
+    /** Detailed breakdown of travel time components */
+    travelTimeBreakdown: EstimatedTravelTime
+    /** Profit per second (floating point for UI display) */
+    profitPerSecond: number
+    /** Profit margin percentage (floating point for UI display) */
+    marginPercent: number
+}
+
+/**
+ * Options for finding deals
+ */
+export interface FindDealsOptions {
+    /** Maximum number of deals to return */
+    maxDeals?: number
+    /** Maximum search distance */
+    maxDistance?: number
+    /** Player's current balance (for affordability filtering) */
+    playerBalance?: UInt64Type
+    /** Minimum profit per second threshold */
+    minProfitPerSecond?: number
+    /** Minimum profit margin percentage */
+    minMarginPercent?: number
+    /** Override available cargo space (in mass units). If provided, uses this instead of calculating from ship's current cargo. */
+    availableSpace?: number
+}
+
+/**
+ * Calculate deals for a ship from a specific origin location
+ */
+export async function findDealsForShip(
+    ship: Ship,
+    originLocation: Coordinates,
+    getNearbyLocations: (origin: Coordinates, maxDistance: number) => Promise<Location[]>,
+    getMarketPrices: (location: Coordinates) => Promise<GoodPrice[]>,
+    options: FindDealsOptions = {}
+): Promise<Deal[]> {
+    const {
+        maxDeals = 10,
+        maxDistance = 20 * PRECISION,
+        playerBalance,
+        minProfitPerSecond = 0,
+        minMarginPercent = 0,
+        availableSpace,
+    } = options
+
+    const balance = playerBalance !== undefined ? UInt64.from(playerBalance) : undefined
+
+    const origin = Location.from(originLocation)
+    const originPrices = await getMarketPrices(originLocation)
+    origin.setMarketPrices(originPrices)
+
+    // Get nearby locations
+    const nearbyLocations = await getNearbyLocations(originLocation, maxDistance)
+
+    const deals: Deal[] = []
+    const currentMass = ship.totalMass
+    const shipCapacity = ship.maxCapacity
+    const effectiveAvailableMass =
+        availableSpace !== undefined
+            ? UInt64.from(availableSpace)
+            : currentMass.lt(shipCapacity)
+            ? shipCapacity.subtracting(currentMass)
+            : UInt64.zero
+
+    // Check each nearby location
+    for (const destLocation of nearbyLocations) {
+        const destinationPrices = await getMarketPrices(destLocation.coordinates)
+        destLocation.setMarketPrices(destinationPrices)
+
+        const distance = distanceBetweenCoordinates(originLocation, destLocation.coordinates)
+
+        // Compare prices for each good
+        for (const originGood of originPrices) {
+            const destGood = destinationPrices.find((g) => g.id.equals(originGood.id))
+            if (!destGood) continue
+
+            if (
+                !isProfitable(originGood.price, destGood.price) ||
+                originGood.supply.equals(UInt16.from(0))
+            ) {
+                continue
+            }
+
+            // Calculate max quantity based on balance, cargo space, and supply
+            const canAfford =
+                balance !== undefined
+                    ? balance.dividing(originGood.price)
+                    : UInt64.from(Number.MAX_SAFE_INTEGER)
+            const canHaul = effectiveAvailableMass.dividing(originGood.good.mass)
+            const supplyLimit = UInt64.from(originGood.supply)
+
+            // Find minimum of canAfford, canHaul, supplyLimit
+            let maxQuantity = canAfford
+            if (canHaul.lt(maxQuantity)) maxQuantity = canHaul
+            if (supplyLimit.lt(maxQuantity)) maxQuantity = supplyLimit
+
+            if (maxQuantity.equals(UInt64.zero)) continue
+
+            // Calculate travel time with cargo (includes recharge + load time)
+            const cargoMass = originGood.good.mass.multiplying(maxQuantity)
+            const availableSpaceUInt = UInt64.from(availableSpace)
+            const baseMass =
+                availableSpace !== undefined
+                    ? shipCapacity.gte(availableSpaceUInt)
+                        ? shipCapacity.subtracting(availableSpaceUInt)
+                        : UInt64.zero
+                    : currentMass
+            const totalMass = baseMass.adding(cargoMass)
+            const needsRecharge = !ship.hasEnergyFor(distance)
+            const travelEstimate = estimateTravelTime(ship as ShipLike, totalMass, distance, {
+                needsRecharge,
+                loadMass: Number(cargoMass),
+            })
+
+            // Calculate profitability metrics using trade.ts functions
+            const tradeCalc = calculateTradeProfit(maxQuantity, originGood.price, destGood.price)
+            const profitPerUnit = destGood.price.subtracting(originGood.price)
+            const profitPerSecond = calculateProfitPerSecond(tradeCalc.profit, travelEstimate.total)
+
+            // Apply filters
+            if (profitPerSecond < minProfitPerSecond) continue
+            if (tradeCalc.margin < minMarginPercent) continue
+
+            deals.push({
+                origin,
+                destination: destLocation,
+                good: originGood,
+                distance,
+                supply: originGood.supply,
+                buyPrice: originGood.price,
+                sellPrice: destGood.price,
+                profitPerUnit,
+                maxQuantity: UInt32.from(maxQuantity),
+                totalProfit: tradeCalc.profit,
+                travelTime: travelEstimate.total,
+                travelTimeBreakdown: travelEstimate,
+                profitPerSecond,
+                marginPercent: tradeCalc.margin,
+            })
+        }
+    }
+
+    // Sort by profit per second (descending)
+    deals.sort((a, b) => b.profitPerSecond - a.profitPerSecond)
+
+    return deals.slice(0, maxDeals)
+}
+
+/**
+ * Find the single best deal for a ship from a specific origin location
+ */
+export async function findBestDeal(
+    ship: Ship,
+    originLocation: Coordinates,
+    getNearbyLocations: (origin: Coordinates, maxDistance: number) => Promise<Location[]>,
+    getMarketPrices: (location: Coordinates) => Promise<GoodPrice[]>,
+    options: FindDealsOptions = {}
+): Promise<Deal | undefined> {
+    const deals = await findDealsForShip(
+        ship,
+        originLocation,
+        getNearbyLocations,
+        getMarketPrices,
+        {
+            ...options,
+            maxDeals: 1,
+        }
+    )
+    return deals[0]
+}

package/src/trading/trade.ts

@@ -0,0 +1,203 @@
+import {Int64, Int64Type, UInt32, UInt32Type, UInt64} from '@wharfkit/antelope'
+import {Ship} from '../entities/ship'
+import {Player} from '../entities/player'
+import {GoodPrice} from '../types'
+
+/**
+ * Trade calculation result
+ */
+export interface TradeCalculation {
+    maxQuantity: number
+    totalCost: number
+    totalMass: UInt64
+    affordableQuantity: number
+    spaceForQuantity: number
+}
+
+/**
+ * Calculate updated weighted average cargo cost after purchase.
+ * Matches contract logic: (paid * owned + cost) / (owned + quantity)
+ *
+ * @param currentPaid - Current average cost per unit (from cargo.paid)
+ * @param currentOwned - Current owned quantity
+ * @param purchaseCost - Total cost of new purchase (price * quantity)
+ * @param purchaseQuantity - Quantity being purchased
+ * @returns New weighted average cost per unit
+ *
+ * @example
+ * // Owned 10 units at 100 each, buying 5 more at 120 each
+ * const newPaid = calculateUpdatedCargoCost(
+ *     UInt64.from(100),
+ *     UInt32.from(10),
+ *     UInt64.from(600),
+ *     UInt32.from(5)
+ * )
+ * // Result: (100*10 + 600) / (10+5) = 106.67 per unit
+ */
+export function calculateUpdatedCargoCost(
+    currentPaid: UInt64,
+    currentOwned: UInt32,
+    purchaseCost: UInt64,
+    purchaseQuantity: UInt32
+): UInt64 {
+    // Match contract: (paid * owned + cost) / (owned + quantity)
+    const numerator = currentPaid.multiplying(currentOwned).adding(purchaseCost)
+    const denominator = UInt32.from(currentOwned).adding(purchaseQuantity)
+    return numerator.dividing(denominator)
+}
+
+/**
+ * Calculate the maximum quantity of a good a ship can buy
+ * considering both space and player balance
+ */
+export function calculateMaxTradeQuantity(
+    ship: Ship,
+    player: Player,
+    goodPrice: GoodPrice
+): TradeCalculation {
+    const pricePerUnit = UInt32.from(goodPrice.price)
+    const massPerUnit = UInt32.from(goodPrice.good.mass)
+
+    const spaceForQuantity = ship.availableCapacity.dividing(massPerUnit)
+    const affordableQuantity = player.balance.dividing(pricePerUnit)
+    const maxQuantity = spaceForQuantity.lt(affordableQuantity)
+        ? spaceForQuantity
+        : affordableQuantity
+
+    return {
+        maxQuantity: Number(maxQuantity),
+        totalCost: Number(maxQuantity.multiplying(pricePerUnit)),
+        totalMass: UInt64.from(maxQuantity.multiplying(massPerUnit)),
+        affordableQuantity: Number(affordableQuantity),
+        spaceForQuantity: Number(spaceForQuantity),
+    }
+}
+
+/**
+ * Trade profit calculation result
+ */
+export interface TradeProfitResult {
+    revenue: UInt64
+    cost: UInt64
+    profit: Int64
+    margin: number
+}
+
+/**
+ * Calculate profit for a trade route
+ */
+export function calculateTradeProfit(
+    quantity: UInt32Type,
+    buyPrice: UInt32Type,
+    sellPrice: UInt32Type
+): TradeProfitResult {
+    const qty = UInt32.from(quantity)
+    const buy = UInt32.from(buyPrice)
+    const sell = UInt32.from(sellPrice)
+
+    const cost = UInt64.from(qty).multiplying(buy)
+    const revenue = UInt64.from(qty).multiplying(sell)
+    const profit = Int64.from(revenue).subtracting(cost)
+    const margin = cost.gt(UInt64.zero) ? (Number(profit) / Number(cost)) * 100 : 0
+
+    return {revenue, cost, profit, margin}
+}
+
+/**
+ * Calculate profit per unit of mass
+ */
+export function calculateProfitPerMass(
+    quantity: number,
+    buyPrice: number,
+    sellPrice: number,
+    massPerUnit: number
+): number {
+    const profit = (sellPrice - buyPrice) * quantity
+    const totalMass = quantity * massPerUnit
+    return totalMass > 0 ? profit / totalMass : 0
+}
+
+/**
+ * Calculate profit per second for a trade route
+ */
+export function calculateProfitPerSecond(profit: Int64Type, travelTimeSeconds: UInt32Type): number {
+    const t = UInt32.from(travelTimeSeconds)
+    return t.gt(UInt32.zero) ? Number(profit) / Number(t) : 0
+}
+
+/**
+ * Find the best good to trade between two locations
+ */
+export function findBestGoodToTrade(
+    ship: Ship,
+    player: Player,
+    originPrices: GoodPrice[],
+    destPrices: GoodPrice[],
+    travelTimeSeconds: UInt32Type
+): {
+    good: GoodPrice
+    quantity: number
+    profit: number
+    profitPerSecond: number
+    margin: number
+} | null {
+    let bestTrade: {
+        good: GoodPrice
+        quantity: number
+        profit: number
+        profitPerSecond: number
+        margin: number
+    } | null = null
+    let bestProfitPerSecond = 0
+
+    for (const originPrice of originPrices) {
+        const destPrice = destPrices.find((p) => p.id.equals(originPrice.id))
+        if (!destPrice) continue
+
+        if (!isProfitable(originPrice.price, destPrice.price)) continue
+
+        const calc = calculateMaxTradeQuantity(ship, player, originPrice)
+        if (calc.maxQuantity === 0) continue
+
+        const tradeResult = calculateTradeProfit(
+            calc.maxQuantity,
+            originPrice.price,
+            destPrice.price
+        )
+        const profitPerSecond = calculateProfitPerSecond(tradeResult.profit, travelTimeSeconds)
+
+        if (profitPerSecond > bestProfitPerSecond) {
+            bestProfitPerSecond = profitPerSecond
+            bestTrade = {
+                good: originPrice,
+                quantity: calc.maxQuantity,
+                profit: Number(tradeResult.profit),
+                profitPerSecond,
+                margin: tradeResult.margin,
+            }
+        }
+    }
+
+    return bestTrade
+}
+
+/**
+ * Calculate break-even price for selling cargo
+ */
+export function calculateBreakEvenPrice(costPaid: number, quantity: number): number {
+    return quantity > 0 ? costPaid / quantity : 0
+}
+
+/**
+ * Check if a trade is profitable
+ */
+export function isProfitable(buyPrice: UInt32Type, sellPrice: UInt32Type): boolean {
+    return UInt32.from(sellPrice).gt(UInt32.from(buyPrice))
+}
+
+/**
+ * Calculate return on investment percentage
+ */
+export function calculateROI(cost: number, profit: number): number {
+    return cost > 0 ? (profit / cost) * 100 : 0
+}