@shipload/sdk 0.7.0 → 1.0.0-beta1

package/src/derivation/strata.ts

@@ -0,0 +1,43 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import type {CoordinatesType} from '../types'
+import {deriveLocationStatic} from '../utils/system'
+import {deriveLocationSize} from './location-size'
+import {deriveResourceStats, deriveStratum, type ResourceStats} from './stratum'
+
+export interface DerivedStratum {
+    index: number
+    itemId: number
+    seed: bigint
+    richness: number
+    reserve: number
+    stats: ResourceStats
+}
+
+export function deriveStrata(
+    coords: CoordinatesType,
+    gameSeed: Checksum256Type,
+    epochSeed: Checksum256Type
+): DerivedStratum[] {
+    const loc = deriveLocationStatic(gameSeed, coords)
+    const locType = Number(loc.type)
+    if (locType === 0) return []
+
+    const size = deriveLocationSize(loc)
+    if (size === 0) return []
+
+    const subtype = Number(loc.subtype)
+    const out: DerivedStratum[] = []
+    for (let i = 0; i < size; i++) {
+        const s = deriveStratum(epochSeed, coords, i, locType, subtype, size)
+        if (s.reserve === 0) continue
+        out.push({
+            index: i,
+            itemId: s.itemId,
+            seed: s.seed,
+            richness: s.richness,
+            reserve: s.reserve,
+            stats: s.seed ? deriveResourceStats(s.seed) : {stat1: 0, stat2: 0, stat3: 0},
+        })
+    }
+    return out
+}

package/src/derivation/stratum.ts

@@ -0,0 +1,134 @@
+import {Bytes, Checksum256, type Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+import {Coordinates, type CoordinatesType} from '../types'
+import {getEligibleResources, getResourceWeight, YIELD_THRESHOLD} from './resources'
+import {RESERVE_TIERS, rollTier, rollWithinTier} from './tiers'
+
+export interface StratumInfo {
+    itemId: number
+    seed: bigint
+    richness: number
+    reserve: number
+}
+
+export interface ResourceStats {
+    stat1: number
+    stat2: number
+    stat3: number
+}
+
+export function deriveStratum(
+    epochSeed: Checksum256Type,
+    coords: CoordinatesType,
+    stratum: number,
+    locationType: number,
+    subtype: number,
+    _maxDepth: number
+): StratumInfo {
+    const seed = Checksum256.from(epochSeed)
+    const c = Coordinates.from(coords)
+    const input = `stratum-${c.x}-${c.y}-${stratum}`
+    const hashResult = hash512(seed, input)
+    const bytes = hashResult.array
+
+    const rawReserve = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0
+
+    let reserve = 0
+    if (rawReserve <= YIELD_THRESHOLD) {
+        const tierRoll = ((bytes[18] << 8) | bytes[19]) >>> 0
+        const withinRoll = ((bytes[20] << 8) | bytes[21]) >>> 0
+        const tier = rollTier(tierRoll, stratum)
+        reserve = rollWithinTier(withinRoll, RESERVE_TIERS[tier])
+    }
+
+    if (reserve === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+
+    const eligible = getEligibleResources(locationType, subtype, stratum)
+    if (eligible.length === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+
+    const resourceRoll = ((bytes[4] << 24) | (bytes[5] << 16) | (bytes[6] << 8) | bytes[7]) >>> 0
+
+    let totalWeight = 0
+    for (const id of eligible) {
+        totalWeight += getResourceWeight(id, stratum)
+    }
+
+    let selectedItemId = eligible[0]
+    if (totalWeight > 0) {
+        const roll = resourceRoll % totalWeight
+        let cumulative = 0
+        for (const id of eligible) {
+            cumulative += getResourceWeight(id, stratum)
+            if (roll < cumulative) {
+                selectedItemId = id
+                break
+            }
+        }
+    }
+
+    const seedBigInt =
+        (BigInt(bytes[8]) << 56n) |
+        (BigInt(bytes[9]) << 48n) |
+        (BigInt(bytes[10]) << 40n) |
+        (BigInt(bytes[11]) << 32n) |
+        (BigInt(bytes[12]) << 24n) |
+        (BigInt(bytes[13]) << 16n) |
+        (BigInt(bytes[14]) << 8n) |
+        BigInt(bytes[15])
+
+    const rawRichness = (bytes[16] << 8) | bytes[17]
+    const normalized = rawRichness / 65535
+    const baseRichness = Math.floor(normalized * normalized * 999) + 1
+
+    let depthBonus = 0
+    if (stratum > 1) {
+        depthBonus = (50 * Math.log(stratum)) / Math.log(65535)
+    }
+    const richness = Math.min(Math.floor(baseRichness + depthBonus), 1000)
+
+    return {itemId: selectedItemId, seed: seedBigInt, richness, reserve}
+}
+
+/**
+ * Derives the three stat values for a raw resource from a deposit's
+ * entropy seed (hash-based, weibull-transformed).
+ *
+ * **Use only on deposit seeds** — the bigint returned by `deriveStratum`
+ * or carried on a `MassDeposit`. Do NOT call this on a cargo item's
+ * `stats` field; cargo stats are bit-packed and must be read via
+ * `decodeStat` (or `decodeStackStats` for category-mapped output).
+ *
+ * Passing a cargo `stats` value here produces meaningless output
+ * (hash of the packed bits, unrelated to the actual stats).
+ */
+export function deriveResourceStats(seed: bigint): ResourceStats {
+    const seedBytes = new Uint8Array(8)
+    for (let i = 0; i < 8; i++) {
+        seedBytes[i] = Number(seed & 0xffn)
+        seed >>= 8n
+    }
+    const hashResult = Checksum256.hash(Bytes.from(seedBytes))
+    const hashBytes = hashResult.array
+
+    const extractU32 = (offset: number): number =>
+        (hashBytes[offset] * 0x1000000 +
+            (hashBytes[offset + 1] << 16) +
+            (hashBytes[offset + 2] << 8) +
+            hashBytes[offset + 3]) >>>
+        0
+
+    const weibull = (raw: number): number => {
+        const u = raw / 4294967296
+        let x = 0.24 * Math.sqrt(-Math.log(1 - u))
+        if (x > 1) x = 1
+        let val = Math.floor(x * 999) + 1
+        if (val > 999) val = 999
+        return val
+    }
+
+    return {
+        stat1: weibull(extractU32(0)),
+        stat2: weibull(extractU32(4)),
+        stat3: weibull(extractU32(8)),
+    }
+}

package/src/derivation/tiers.ts

@@ -0,0 +1,54 @@
+export type ReserveTier = 'small' | 'medium' | 'large' | 'massive' | 'motherlode'
+
+export interface TierRange {
+    min: number
+    max: number
+}
+
+export const RESERVE_TIERS: Record<ReserveTier, TierRange> = {
+    small: {min: 15, max: 60},
+    medium: {min: 100, max: 200},
+    large: {min: 400, max: 700},
+    massive: {min: 1000, max: 2500},
+    motherlode: {min: 4000, max: 10000},
+}
+
+const SHALLOW_THRESHOLDS = {
+    small: 0.8,
+    medium: 0.991946,
+    large: 0.999946,
+    massive: 0.999996,
+}
+
+const DEEP_THRESHOLDS = {
+    small: 0.5,
+    medium: 0.95892,
+    large: 0.99892,
+    massive: 0.99992,
+}
+
+export const TIER_ROLL_MAX = 0x10000 // 65536
+
+function lerp(a: number, b: number, t: number): number {
+    return a + (b - a) * t
+}
+
+export function rollTier(tierRoll: number, stratum: number): ReserveTier {
+    const d = Math.min(stratum, 65535) / 65535
+    const smallMax = lerp(SHALLOW_THRESHOLDS.small, DEEP_THRESHOLDS.small, d) * TIER_ROLL_MAX
+    const mediumMax = lerp(SHALLOW_THRESHOLDS.medium, DEEP_THRESHOLDS.medium, d) * TIER_ROLL_MAX
+    const largeMax = lerp(SHALLOW_THRESHOLDS.large, DEEP_THRESHOLDS.large, d) * TIER_ROLL_MAX
+    const massiveMax = lerp(SHALLOW_THRESHOLDS.massive, DEEP_THRESHOLDS.massive, d) * TIER_ROLL_MAX
+
+    if (tierRoll < smallMax) return 'small'
+    if (tierRoll < mediumMax) return 'medium'
+    if (tierRoll < largeMax) return 'large'
+    if (tierRoll < massiveMax) return 'massive'
+    return 'motherlode'
+}
+
+export function rollWithinTier(withinRoll: number, range: TierRange): number {
+    const u = withinRoll / 65535
+    const skewed = u * u
+    return Math.floor(range.min + skewed * (range.max - range.min))
+}

package/src/entities/cargo-utils.ts

@@ -0,0 +1,84 @@
+import {UInt32, UInt64, type 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 getCargoForItem(
+    cargo: EntityInventory[],
+    goodId: UInt64Type
+): EntityInventory | undefined {
+    return cargo.find((c) => c.item_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 function afterRemoveItems(
+    cargo: ServerContract.Types.cargo_item[],
+    goodsToRemove: Array<{goodId: number; quantity: number}>
+): EntityInventory[] {
+    if (cargo.length === 0) {
+        return []
+    }
+
+    return cargo.map((item) => {
+        const removeItem = goodsToRemove.find((s) => Number(item.item_id) === s.goodId)
+        if (!removeItem) {
+            return new EntityInventory(item)
+        }
+
+        const currentQty = Number(item.quantity)
+        const newQty = Math.max(0, currentQty - removeItem.quantity)
+
+        return new EntityInventory(
+            ServerContract.Types.cargo_item.from({
+                item_id: item.item_id,
+                quantity: UInt32.from(newQty),
+            })
+        )
+    })
+}
+
+export function afterRemoveAllItems(cargo: ServerContract.Types.cargo_item[]): EntityInventory[] {
+    if (cargo.length === 0) {
+        return []
+    }
+
+    return cargo.map(
+        (item) =>
+            new EntityInventory(
+                ServerContract.Types.cargo_item.from({
+                    item_id: item.item_id,
+                    quantity: UInt32.from(0),
+                })
+            )
+    )
+}

package/src/entities/container.ts

@@ -0,0 +1,108 @@
+import {UInt64, type UInt64Type} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import type {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
+    cargo?: ServerContract.Types.cargo_item[]
+    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 {
+        this._sched ??= new ScheduleAccessor(this)
+        return this._sched
+    }
+
+    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
+    }
+}
+
+export function computeContainerCapabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const density = stats['density'] ?? 500
+    const strength = stats['strength'] ?? 500
+    const hardness = stats['hardness'] ?? 500
+    const saturation = stats['saturation'] ?? 500
+
+    const hullmass = 25000 + 75 * density
+
+    const statSum = strength + hardness + saturation
+    const exponent = statSum / 2997
+    const capacity = Math.floor(1000000 * 10 ** exponent)
+
+    return {hullmass, capacity}
+}
+
+export function computeContainerT2Capabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const strength = stats['strength'] ?? 0
+    const density = stats['density'] ?? 0
+    const hardness = stats['hardness'] ?? 0
+    const saturation = stats['saturation'] ?? 0
+
+    const hullmass = 20000 + 50 * density
+
+    const statSum = strength + hardness + saturation
+    const exponent = statSum / 2500
+    const capacity = Math.floor(1500000 * 10 ** exponent)
+
+    return {hullmass, capacity}
+}

package/src/entities/entity-inventory.ts

@@ -0,0 +1,39 @@
+import {UInt32, UInt64} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import {getItem} from '../data/catalog'
+import type {Item} from '../types'
+
+export class EntityInventory extends ServerContract.Types.cargo_item {
+    private _item?: Item
+
+    get item(): Item {
+        if (!this._item) {
+            this._item = getItem(this.item_id)
+        }
+        return this._item
+    }
+
+    get good(): Item {
+        return this.item
+    }
+
+    get name(): string {
+        return this.item.name
+    }
+
+    get unitMass(): UInt32 {
+        return UInt32.from(this.item.mass)
+    }
+
+    get totalMass(): UInt64 {
+        return UInt64.from(this.unitMass).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, type UInt64} from '@wharfkit/antelope'
+import {type PlatformContract, ServerContract} from '../contracts'
+import {type 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,42 @@
+import {UInt64, type UInt64Type} from '@wharfkit/antelope'
+import {EntityInventory} from './entity-inventory'
+import type {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))
+    }
+
+    forItem(goodId: UInt64Type): EntityInventory | undefined {
+        return this.items.find((c) => c.item_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)
+}