@shipload/sdk 0.7.1 → 2.0.0-rc2

package/src/entities/cargo-utils.ts

@@ -0,0 +1,142 @@
+import {UInt32, UInt64, UInt64Type} from '@wharfkit/antelope'
+import {EntityInventory} from './entity-inventory'
+import {ServerContract} from '../contracts'
+
+export interface CargoData {
+    cargo: EntityInventory[]
+}
+
+export function totalCargoMass(cargo: EntityInventory[]): UInt64 {
+    return cargo.reduce((sum, c) => {
+        return sum.adding(c.totalMass)
+    }, UInt64.from(0))
+}
+
+export function cargoValue(cargo: EntityInventory[]): UInt64 {
+    return cargo.reduce((sum, c) => {
+        return sum.adding(c.totalCost)
+    }, UInt64.from(0))
+}
+
+export function getCargoForGood(
+    cargo: EntityInventory[],
+    goodId: UInt64Type
+): EntityInventory | undefined {
+    return cargo.find((c) => c.good_id.equals(goodId))
+}
+
+export function hasSpace(
+    currentMass: UInt64,
+    maxCapacity: UInt64,
+    goodMass: UInt64,
+    quantity: number
+): boolean {
+    const additionalMass = goodMass.multiplying(quantity)
+    const totalMass = currentMass.adding(additionalMass)
+    return totalMass.lte(maxCapacity)
+}
+
+export function availableCapacity(currentMass: UInt64, maxCapacity: UInt64): UInt64 {
+    if (currentMass.gte(maxCapacity)) {
+        return UInt64.from(0)
+    }
+    return maxCapacity.subtracting(currentMass)
+}
+
+export function isFull(currentMass: UInt64, maxCapacity: UInt64): boolean {
+    return currentMass.gte(maxCapacity)
+}
+
+export interface SaleValue {
+    revenue: UInt64
+    profit: UInt64
+    cost: UInt64
+}
+
+export function calculateSaleValue(
+    cargo: ServerContract.Types.cargo_item[],
+    prices: Map<number, UInt64>
+): SaleValue {
+    if (cargo.length === 0) {
+        return {revenue: UInt64.from(0), profit: UInt64.from(0), cost: UInt64.from(0)}
+    }
+
+    let revenue = UInt64.from(0)
+    let cost = UInt64.from(0)
+
+    for (const item of cargo) {
+        if (UInt32.from(item.quantity).equals(UInt32.from(0))) continue
+
+        const goodId = Number(item.good_id)
+        const salePrice = prices.get(goodId)
+
+        if (salePrice) {
+            revenue = revenue.adding(salePrice.multiplying(item.quantity))
+        }
+
+        cost = cost.adding(item.unit_cost.multiplying(item.quantity))
+    }
+
+    const profit = revenue.gte(cost) ? revenue.subtracting(cost) : UInt64.from(0)
+
+    return {
+        revenue,
+        profit,
+        cost,
+    }
+}
+
+export function calculateSaleValueFromArray(
+    cargo: ServerContract.Types.cargo_item[],
+    prices: UInt64[]
+): SaleValue {
+    const priceMap = new Map<number, UInt64>()
+    prices.forEach((price, index) => {
+        priceMap.set(index, price)
+    })
+    return calculateSaleValue(cargo, priceMap)
+}
+
+export function afterSellGoods(
+    cargo: ServerContract.Types.cargo_item[],
+    goodsToSell: Array<{goodId: number; quantity: number}>
+): EntityInventory[] {
+    if (cargo.length === 0) {
+        return []
+    }
+
+    return cargo.map((item) => {
+        const saleItem = goodsToSell.find((s) => Number(item.good_id) === s.goodId)
+        if (!saleItem) {
+            return new EntityInventory(item)
+        }
+
+        const currentQty = Number(item.quantity)
+        const newQty = Math.max(0, currentQty - saleItem.quantity)
+
+        return new EntityInventory(
+            ServerContract.Types.cargo_item.from({
+                good_id: item.good_id,
+                quantity: UInt32.from(newQty),
+                unit_cost: item.unit_cost,
+            })
+        )
+    })
+}
+
+export function afterSellAllGoods(cargo: ServerContract.Types.cargo_item[]): EntityInventory[] {
+    if (cargo.length === 0) {
+        return []
+    }
+
+    return cargo.map(
+        (item) =>
+            new EntityInventory(
+                ServerContract.Types.cargo_item.from({
+                    good_id: item.good_id,
+                    quantity: UInt32.from(0),
+                    unit_cost: item.unit_cost,
+                })
+            )
+    )
+}

package/src/entities/container.ts

@@ -0,0 +1,70 @@
+import {UInt64, UInt64Type} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import {CoordinatesType} from '../types'
+import {Location} from './location'
+import {ScheduleAccessor} from '../scheduling/accessor'
+import * as schedule from '../scheduling/schedule'
+
+export interface ContainerStateInput {
+    id: UInt64Type
+    owner: string
+    name: string
+    coordinates: CoordinatesType | {x: number; y: number; z?: number}
+    hullmass: number
+    capacity: number
+    cargomass?: number
+    schedule?: ServerContract.Types.schedule
+}
+
+export class Container extends ServerContract.Types.entity_info {
+    private _sched?: ScheduleAccessor
+
+    get name(): string {
+        return this.entity_name
+    }
+
+    get sched(): ScheduleAccessor {
+        return (this._sched ??= new ScheduleAccessor(this))
+    }
+
+    get isIdle(): boolean {
+        return this.is_idle
+    }
+
+    isLoading(now: Date): boolean {
+        return schedule.isLoading(this, now)
+    }
+
+    isUnloading(now: Date): boolean {
+        return schedule.isUnloading(this, now)
+    }
+
+    get location(): Location {
+        return Location.from(this.coordinates)
+    }
+
+    get totalMass(): UInt64 {
+        return UInt64.from(this.hullmass ?? 0).adding(this.cargomass)
+    }
+
+    get maxCapacity(): UInt64 {
+        return UInt64.from(this.capacity)
+    }
+
+    get availableCapacity(): UInt64 {
+        const cargo = UInt64.from(this.cargomass)
+        return cargo.gte(this.maxCapacity) ? UInt64.from(0) : this.maxCapacity.subtracting(cargo)
+    }
+
+    hasSpace(additionalMass: UInt64): boolean {
+        return UInt64.from(this.cargomass).adding(additionalMass).lte(this.maxCapacity)
+    }
+
+    get isFull(): boolean {
+        return UInt64.from(this.cargomass).gte(this.maxCapacity)
+    }
+
+    get orbitalAltitude(): number {
+        return this.coordinates.z?.toNumber() || 0
+    }
+}

package/src/entities/entity-inventory.ts

@@ -0,0 +1,39 @@
+import {UInt32, UInt64} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import {getGood} from '../market/goods'
+import {Good} from '../types'
+
+export class EntityInventory extends ServerContract.Types.cargo_item {
+    private _good?: Good
+
+    get good(): Good {
+        if (!this._good) {
+            this._good = getGood(this.good_id)
+        }
+        return this._good
+    }
+
+    get name(): string {
+        return this.good.name
+    }
+
+    get unitMass(): UInt32 {
+        return this.good.mass
+    }
+
+    get totalMass(): UInt64 {
+        return UInt64.from(this.unitMass).multiplying(this.quantity)
+    }
+
+    get totalCost(): UInt64 {
+        return this.unit_cost.multiplying(this.quantity)
+    }
+
+    get hasCargo(): boolean {
+        return UInt32.from(this.quantity).gt(UInt32.from(0))
+    }
+
+    get isEmpty(): boolean {
+        return UInt32.from(this.quantity).equals(UInt32.from(0))
+    }
+}

package/src/entities/gamestate.ts

@@ -0,0 +1,152 @@
+import {Checksum256, Int64, UInt64} from '@wharfkit/antelope'
+import {PlatformContract, ServerContract} from '../contracts'
+import {EpochInfo, getCurrentEpoch, getEpochInfo} from '../scheduling/epoch'
+import {hasSystem} from '../utils/system'
+
+/**
+ * GameState class extends the state_row from the server contract
+ * with helper methods for epoch management and system generation
+ */
+export class GameState extends ServerContract.Types.state_row {
+    private _game?: PlatformContract.Types.game_row
+
+    /**
+     * Create a GameState instance from a state_row
+     */
+    static from(
+        state: ServerContract.Types.state_row,
+        game?: PlatformContract.Types.game_row
+    ): GameState {
+        const gameState = Object.create(GameState.prototype) as GameState
+        Object.assign(gameState, state)
+        gameState._game = game
+        return gameState
+    }
+
+    /**
+     * Set the game configuration (needed for epoch calculations)
+     */
+    setGame(game: PlatformContract.Types.game_row): void {
+        this._game = game
+    }
+
+    /**
+     * Get the current epoch number from the state
+     */
+    get currentEpoch(): UInt64 {
+        return this.epoch
+    }
+
+    /**
+     * Get the epoch seed (used for market pricing and system generation)
+     */
+    get epochSeed(): Checksum256 {
+        return this.seed
+    }
+
+    /**
+     * Get the game seed (from game config, if available)
+     */
+    get gameSeed(): Checksum256 | undefined {
+        return this._game?.config.seed
+    }
+
+    /**
+     * Check if the game is currently enabled
+     */
+    get isEnabled(): boolean {
+        return this.enabled
+    }
+
+    /**
+     * Get the total number of ships in the game
+     */
+    get shipCount(): number {
+        return Number(this.ships)
+    }
+
+    /**
+     * Get the current salt value (used for random number generation)
+     */
+    get currentSalt(): UInt64 {
+        return this.salt
+    }
+
+    /**
+     * Get the commit hash for the next epoch
+     */
+    get nextEpochCommit(): Checksum256 {
+        return this.commit
+    }
+
+    /**
+     * Calculate the current epoch from game config (if game is set)
+     * This might differ from state.epoch if the blockchain hasn't advanced yet
+     */
+    get calculatedCurrentEpoch(): UInt64 | undefined {
+        if (!this._game) {
+            return undefined
+        }
+        return getCurrentEpoch(this._game)
+    }
+
+    /**
+     * Get epoch info (start/end times) for the current epoch
+     */
+    get currentEpochInfo(): EpochInfo | undefined {
+        if (!this._game) {
+            return undefined
+        }
+        return getEpochInfo(this._game, this.epoch)
+    }
+
+    /**
+     * Get epoch info for a specific epoch number
+     */
+    getEpochInfo(epoch: UInt64): EpochInfo | undefined {
+        if (!this._game) {
+            return undefined
+        }
+        return getEpochInfo(this._game, epoch)
+    }
+
+    /**
+     * Check if a system exists at given coordinates
+     * Requires game seed from game config
+     */
+    hasSystemAt(x: number, y: number): boolean {
+        if (!this._game) {
+            return false
+        }
+        return hasSystem(this._game.config.seed, {x: Int64.from(x), y: Int64.from(y)})
+    }
+
+    /**
+     * Check if a system exists at coordinates object
+     */
+    hasSystemAtCoords(coords: ServerContract.Types.coordinates): boolean {
+        if (!this._game) {
+            return false
+        }
+        return hasSystem(this._game.config.seed, coords)
+    }
+
+    /**
+     * Get a summary of the game state
+     */
+    get summary(): {
+        enabled: boolean
+        epoch: string
+        ships: number
+        hasSeed: boolean
+        hasCommit: boolean
+    } {
+        return {
+            enabled: this.enabled,
+            epoch: this.epoch.toString(),
+            ships: this.shipCount,
+            hasSeed: !this.seed.equals(Checksum256.from('0'.repeat(64))),
+            hasCommit: !this.commit.equals(Checksum256.from('0'.repeat(64))),
+        }
+    }
+}

package/src/entities/inventory-accessor.ts

@@ -0,0 +1,46 @@
+import {UInt64, UInt64Type} from '@wharfkit/antelope'
+import {EntityInventory} from './entity-inventory'
+import {HasCargo} from '../capabilities/storage'
+
+export type {HasCargo}
+
+export class InventoryAccessor {
+    private _items?: EntityInventory[]
+
+    constructor(private readonly entity: HasCargo) {}
+
+    get items(): EntityInventory[] {
+        if (!this._items) {
+            this._items = this.entity.cargo.map((item) => new EntityInventory(item))
+        }
+        return this._items
+    }
+
+    get totalMass(): UInt64 {
+        return this.items.reduce((sum, c) => sum.adding(c.totalMass), UInt64.from(0))
+    }
+
+    get totalValue(): UInt64 {
+        return this.items.reduce((sum, c) => sum.adding(c.totalCost), UInt64.from(0))
+    }
+
+    forGood(goodId: UInt64Type): EntityInventory | undefined {
+        return this.items.find((c) => c.good_id.equals(goodId))
+    }
+
+    get sellable(): EntityInventory[] {
+        return this.items.filter((c) => c.hasCargo)
+    }
+
+    get hasSellable(): boolean {
+        return this.items.some((c) => c.hasCargo)
+    }
+
+    get sellableCount(): number {
+        return this.items.filter((c) => c.hasCargo).length
+    }
+}
+
+export function createInventoryAccessor(entity: HasCargo): InventoryAccessor {
+    return new InventoryAccessor(entity)
+}

package/src/entities/location.ts

@@ -0,0 +1,255 @@
+import {Checksum256, Checksum256Type, UInt16, UInt16Type, UInt64} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import {Coordinates, CoordinatesType, Distance, GoodPrice, LocationType} from '../types'
+import {getLocationType, hasSystem, isExtractableLocation} from '../utils/system'
+import {findNearbyPlanets} from '../travel/travel'
+
+/**
+ * Location helper class for working with game coordinates.
+ * Provides system detection, market price caching, nearby planet finding, and supply tracking.
+ */
+export class Location {
+    readonly coordinates: Coordinates
+    private _marketPrices?: GoodPrice[]
+    private _gameSeed?: Checksum256
+    private _hasSystem?: boolean
+    private _locationRows?: ServerContract.Types.supply_row[]
+    private _epoch?: UInt64
+
+    constructor(coordinates: CoordinatesType) {
+        this.coordinates = Coordinates.from(coordinates)
+    }
+
+    /**
+     * Create a Location from coordinates
+     */
+    static from(coordinates: CoordinatesType): Location {
+        return new Location(Coordinates.from(coordinates))
+    }
+
+    /**
+     * Check if this location has a system (planet, asteroid, or nebula)
+     */
+    hasSystemAt(gameSeed: Checksum256Type): boolean {
+        const seed = Checksum256.from(gameSeed)
+        if (this._hasSystem === undefined || !this._gameSeed?.equals(seed)) {
+            this._gameSeed = seed
+            this._hasSystem = hasSystem(seed, this.coordinates)
+        }
+        return this._hasSystem
+    }
+
+    /**
+     * Get the location type (EMPTY, PLANET, ASTEROID, or NEBULA)
+     */
+    getLocationTypeAt(gameSeed: Checksum256Type): LocationType {
+        return getLocationType(gameSeed, this.coordinates)
+    }
+
+    /**
+     * Check if this location is extractable (asteroid or nebula)
+     */
+    isExtractableAt(gameSeed: Checksum256Type): boolean {
+        return isExtractableLocation(this.getLocationTypeAt(gameSeed))
+    }
+
+    /**
+     * Set cached market prices for this location
+     */
+    setMarketPrices(prices: GoodPrice[]): void {
+        this._marketPrices = prices
+    }
+
+    /**
+     * Get cached market prices (returns undefined if not cached)
+     */
+    get marketPrices(): GoodPrice[] | undefined {
+        return this._marketPrices
+    }
+
+    /**
+     * Get price for a specific good (from cache)
+     */
+    getPrice(goodId: UInt16Type): GoodPrice | undefined {
+        if (!this._marketPrices) return undefined
+        return this._marketPrices.find((p) => p.id.equals(goodId))
+    }
+
+    /**
+     * Find nearby planets from this location
+     */
+    findNearby(gameSeed: Checksum256Type, maxDistance: UInt16Type = 20): Distance[] {
+        return findNearbyPlanets(Checksum256.from(gameSeed), this.coordinates, maxDistance)
+    }
+
+    /**
+     * Check if this location equals another location
+     */
+    equals(other: CoordinatesType | Location): boolean {
+        const otherCoords = other instanceof Location ? other.coordinates : Coordinates.from(other)
+        return this.coordinates.equals(otherCoords)
+    }
+
+    /**
+     * Set location rows (supply data) for this location
+     */
+    setLocationRows(rows: ServerContract.Types.supply_row[], epoch: UInt64): void {
+        this._locationRows = rows
+        this._epoch = epoch
+    }
+
+    /**
+     * Get cached location rows (supply data)
+     */
+    get locationRows(): ServerContract.Types.supply_row[] | undefined {
+        return this._locationRows
+    }
+
+    /**
+     * Get supply for a specific good at this location
+     * Returns undefined if location rows not cached or good not found
+     */
+    getSupply(goodId: UInt16Type): UInt16 | undefined {
+        if (!this._locationRows) return undefined
+        const row = this._locationRows.find(
+            (r) => r.good_id.equals(goodId) && this._epoch && r.epoch.equals(this._epoch)
+        )
+        return row ? row.supply : undefined
+    }
+
+    /**
+     * Get all available goods at this location (goods with supply > 0)
+     * Returns undefined if location rows not cached
+     */
+    get availableGoods(): ServerContract.Types.supply_row[] | undefined {
+        if (!this._locationRows) return undefined
+        return this._locationRows.filter(
+            (r) => this._epoch && r.epoch.equals(this._epoch) && r.supply.gt(UInt16.from(0))
+        )
+    }
+
+    /**
+     * Check if a specific good is available (has supply)
+     * Returns false if location rows not cached
+     */
+    hasGood(goodId: UInt16Type): boolean {
+        const supply = this.getSupply(goodId)
+        return supply !== undefined && supply.gt(UInt16.from(0))
+    }
+
+    /**
+     * Get the epoch for cached location data
+     */
+    get epoch(): UInt64 | undefined {
+        return this._epoch
+    }
+
+    /**
+     * Check if cached data exists
+     */
+    get hasCachedData(): boolean {
+        return this._marketPrices !== undefined || this._locationRows !== undefined
+    }
+
+    /**
+     * Check if supply data is cached
+     */
+    get hasSupplyData(): boolean {
+        return this._locationRows !== undefined
+    }
+
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void {
+        this._marketPrices = undefined
+        this._locationRows = undefined
+        this._epoch = undefined
+    }
+
+    /**
+     * Create optimistic Location with updated supply after purchase/sale.
+     * Matches contract: update_location_supply (delta can be positive or negative)
+     * Contract reference: market.cpp:53, 123-151
+     *
+     * @param goodId - Good ID to update supply for
+     * @param quantityDelta - Change in supply (negative for purchase, positive for sale)
+     * @returns New Location with updated supply in cached data
+     *
+     * @example
+     * // After buying 10 units (supply decreases)
+     * const newLocation = location.withUpdatedSupply(1, -10)
+     *
+     * // After selling 5 units (supply increases)
+     * const newLocation = location.withUpdatedSupply(1, 5)
+     */
+    withUpdatedSupply(goodId: UInt16Type, quantityDelta: number): Location {
+        const newLocation = Location.from(this.coordinates)
+
+        // Copy market prices if cached
+        if (this._marketPrices) {
+            newLocation._marketPrices = this._marketPrices.map((price) => {
+                if (price.id.equals(goodId)) {
+                    const currentSupply = UInt16.from(price.supply)
+                    const delta = UInt16.from(Math.abs(quantityDelta))
+                    const newSupply =
+                        quantityDelta < 0
+                            ? currentSupply.gte(delta)
+                                ? currentSupply.subtracting(delta)
+                                : UInt16.from(0)
+                            : currentSupply.adding(quantityDelta)
+
+                    return GoodPrice.from({
+                        id: price.id,
+                        good: price.good,
+                        price: price.price,
+                        supply: newSupply,
+                    })
+                }
+                return price
+            })
+        }
+
+        // Copy location rows if cached
+        if (this._locationRows && this._epoch) {
+            newLocation._locationRows = this._locationRows.map((row) => {
+                if (row.good_id.equals(goodId) && row.epoch.equals(this._epoch!)) {
+                    const currentSupply = UInt16.from(row.supply)
+                    const delta = UInt16.from(Math.abs(quantityDelta))
+                    const newSupply =
+                        quantityDelta < 0
+                            ? currentSupply.gte(delta)
+                                ? currentSupply.subtracting(delta)
+                                : UInt16.from(0)
+                            : currentSupply.adding(quantityDelta)
+
+                    return ServerContract.Types.supply_row.from({
+                        id: row.id,
+                        coordinates: row.coordinates,
+                        epoch: row.epoch,
+                        good_id: row.good_id,
+                        supply: newSupply,
+                    })
+                }
+                return row
+            })
+            newLocation._epoch = this._epoch
+        }
+
+        // Copy other cached data
+        newLocation._gameSeed = this._gameSeed
+        newLocation._hasSystem = this._hasSystem
+
+        return newLocation
+    }
+}
+
+/**
+ * Helper function to convert various coordinate types to Location
+ */
+export function toLocation(coords: CoordinatesType | Location): Location {
+    if (coords instanceof Location) {
+        return coords
+    }
+    return Location.from(coords)
+}