@shipload/sdk 1.0.0-next.72 → 1.0.0-next.74

package/src/influence/influence.test.ts

@@ -1,6 +1,5 @@
 import {describe, expect, test} from 'bun:test'
-import {Checksum256, UInt8, UInt16, UInt64} from '@wharfkit/antelope'
-import type {ServerContract} from '../contracts'
+import {Checksum256} from '@wharfkit/antelope'
 import {ITEM_ORE_T1, ITEM_PLATE, ITEM_CRYSTAL_T1} from '../data/item-ids'
 import {categoryIndex} from './categories'
 import {
@@ -20,9 +19,10 @@ import {
     popcount5,
 } from './demand'
 import {findDecomp, DECOMP_REGISTRY} from './decomp'
-import {civicDropoffDuration, depotTransferDuration, contributeDuration} from './duration'
+import {contributeDuration} from './duration'
 import {getStatCount, statsSumSq} from './quality'
-import {pricingFromWeights, valueCargoItem, valueContribution} from './valuation'
+import {explainCargoItem, pricingFromWeights, valueCargoItem, valueContribution} from './valuation'
+import {getItems} from '../data/catalog'
 import {citizenryName, citizenryPatternCount} from './citizenry'
 import citizenryAdjectives from '../data/citizenry-adjectives.json'
 import citizenryNouns from '../data/citizenry-nouns.json'
@@ -155,6 +155,53 @@ describe('decomposition', () => {
     })
 })
 
+describe('explainCargoItem', () => {
+    test('factors reproduce valueCargoItem for every valuable catalog item', () => {
+        const acute = buildDemand(0, categoryIndex('regolith'), DEMAND_TRIPLE_SEED)
+        for (const def of getItems()) {
+            if (def.type !== 'resource' && def.type !== 'component') continue
+            const item = {itemId: Number(def.id), quantity: 7, stats: packStats(363, 535, 246)}
+            const explained = explainCargoItem(item, acute, pricing)
+            expect(explained.totalAtomic).toBe(valueCargoItem(item, acute, pricing))
+        }
+    })
+
+    test('a resource explains mass, weight, quality and need', () => {
+        const acute = buildDemand(0, categoryIndex('crystal'), DEMAND_TRIPLE_SEED)
+        const explained = explainCargoItem(
+            {itemId: ITEM_CRYSTAL_T1, quantity: 5000, stats: packStats(PAR)},
+            acute,
+            pricing
+        )
+        if (explained.kind !== 'resource') throw new Error('expected resource')
+        expect(explained.mass).toBe(
+            BigInt(getItems().find((i) => Number(i.id) === ITEM_CRYSTAL_T1)!.mass) * 5000n
+        )
+        expect(explained.weight).toBe(1)
+        expect(explained.quality).toBeCloseTo(1, 6)
+        expect(explained.need).toBe(2)
+        expect(explained.points).toBeCloseTo(
+            (Number(explained.mass) / 10) * explained.weight * explained.quality * explained.need,
+            3
+        )
+    })
+
+    test('a component explains raw mass, material weight, quality and effort', () => {
+        const explained = explainCargoItem(
+            {itemId: ITEM_PLATE, quantity: 3, stats: packStats(PAR)},
+            baseDemand,
+            pricing
+        )
+        if (explained.kind !== 'component') throw new Error('expected component')
+        const entry = findDecomp(ITEM_PLATE)!
+        const raw = entry.buckets.reduce((sum, b) => sum + b.rawMass, 0)
+        expect(explained.rawMass).toBe(raw * 3)
+        expect(explained.processedMass).toBe(entry.processedMass * 3)
+        expect(explained.weight).toBeGreaterThanOrEqual(1)
+        expect(explained.baseAtomic + explained.effortAtomic).toBe(explained.totalAtomic)
+    })
+})
+
 describe('valuation', () => {
     test('a tonne of par T1 ore at base demand is worth exactly one point', () => {
         const value = valueCargoItem(
@@ -316,135 +363,3 @@ describe('scales', () => {
         expect(NEED_FP_SCALE % INFLUENCE_ATOMIC_PER_POINT).toBe(0)
     })
 })
-
-describe('depot transfer duration', () => {
-    type ModuleEntry = ServerContract.Types.module_entry
-    const DEPOT_ITEM = 10219
-    const LOADER_T1 = 10103
-
-    function makeModuleEntry(itemId: number, stats: bigint): ModuleEntry {
-        return {
-            type: UInt8.from(0),
-            installed: {item_id: UInt16.from(itemId), stats: UInt64.from(stats)},
-        } as unknown as ModuleEntry
-    }
-    function emptySlot(): ModuleEntry {
-        return {type: UInt8.from(0)} as unknown as ModuleEntry
-    }
-
-    // A spawned depot: loader in slot 0, four empty bays after it.
-    const depotWithLoader = (): ModuleEntry[] => [
-        makeModuleEntry(LOADER_T1, packStats(500)),
-        emptySlot(),
-        emptySlot(),
-        emptySlot(),
-        emptySlot(),
-    ]
-    const params = (overrides: Record<string, unknown> = {}) => ({
-        depotModules: depotWithLoader(),
-        depotItemId: DEPOT_ITEM,
-        depotKind: 'depot',
-        depotZ: 0,
-        shipKind: 'ship',
-        shipZ: 0,
-        cargoMass: 100,
-        ...overrides,
-    })
-
-    test('drives off the depot loader, not the ship', () => {
-        expect(depotTransferDuration(params())).toBeGreaterThan(0)
-    })
-
-    test('grows with cargo mass', () => {
-        expect(depotTransferDuration(params({cargoMass: 10_000}))).toBeGreaterThan(
-            depotTransferDuration(params({cargoMass: 100}))
-        )
-    })
-
-    test('empty cargo costs nothing', () => {
-        expect(depotTransferDuration(params({cargoMass: 0}))).toBe(0)
-    })
-
-    test('a depot with no loader installed cannot transfer', () => {
-        expect(depotTransferDuration(params({depotModules: [emptySlot()]}))).toBe(0)
-    })
-
-    test('co-located transfers are floored at the orbital minimum distance', () => {
-        // max(planetary 100, orbital 200) = 200, so anything under 200 reads as 200
-        const touching = depotTransferDuration(params({shipZ: 0, depotZ: 0}))
-        const under = depotTransferDuration(params({shipZ: 150, depotZ: 0}))
-        const over = depotTransferDuration(params({shipZ: 400, depotZ: 0}))
-        expect(under).toBe(touching)
-        expect(over).toBeGreaterThan(touching)
-    })
-
-    test('never reports zero for real cargo', () => {
-        expect(depotTransferDuration(params({cargoMass: 1}))).toBeGreaterThanOrEqual(1)
-    })
-})
-
-describe('civic drop-off duration', () => {
-    type ModuleEntry = ServerContract.Types.module_entry
-    const DEPOT_ITEM = 10219
-    const WORKSHOP_ITEM = 10208
-    const LOADER_T1 = 10103
-
-    function makeModuleEntry(itemId: number, stats: bigint): ModuleEntry {
-        return {
-            type: UInt8.from(0),
-            installed: {item_id: UInt16.from(itemId), stats: UInt64.from(stats)},
-        } as unknown as ModuleEntry
-    }
-    function emptySlot(): ModuleEntry {
-        return {type: UInt8.from(0)} as unknown as ModuleEntry
-    }
-
-    const withLoader = () => ({
-        buildingModules: [makeModuleEntry(LOADER_T1, packStats(500)), emptySlot()],
-        buildingItemId: DEPOT_ITEM,
-        buildingKind: 'depot',
-        buildingZ: 0,
-        shipKind: 'ship',
-        shipZ: 400,
-        cargoMass: 100,
-    })
-    const withoutLoader = () => ({
-        buildingModules: [] as ModuleEntry[],
-        buildingItemId: WORKSHOP_ITEM,
-        buildingKind: 'workshop',
-        buildingZ: 0,
-        shipKind: 'ship',
-        shipZ: 400,
-        cargoMass: 100,
-    })
-
-    test('a building with a slot-0 loader prices off that loader', () => {
-        const p = withLoader()
-        expect(civicDropoffDuration(p)).toBe(
-            depotTransferDuration({
-                depotModules: p.buildingModules,
-                depotItemId: p.buildingItemId,
-                depotKind: p.buildingKind,
-                depotZ: p.buildingZ,
-                shipKind: p.shipKind,
-                shipZ: p.shipZ,
-                cargoMass: p.cargoMass,
-            })
-        )
-    })
-
-    test('a building with no loader falls back to the civic loader', () => {
-        const p = withoutLoader()
-        expect(civicDropoffDuration(p)).toBe(contributeDuration(p.cargoMass, p.shipZ))
-        expect(civicDropoffDuration(p)).toBeGreaterThan(0)
-    })
-
-    test('grows with cargo mass on both paths', () => {
-        expect(civicDropoffDuration({...withLoader(), cargoMass: 10_000})).toBeGreaterThan(
-            civicDropoffDuration(withLoader())
-        )
-        expect(civicDropoffDuration({...withoutLoader(), cargoMass: 10_000})).toBeGreaterThan(
-            civicDropoffDuration(withoutLoader())
-        )
-    })
-})

package/src/influence/valuation.ts

@@ -126,6 +126,81 @@ export function valueCargoItem(
     return withEffort
 }
 
+export interface ResourceValuation {
+    kind: 'resource'
+    category: number
+    tier: number
+    mass: bigint
+    weight: number
+    quality: number
+    need: number
+    totalAtomic: bigint
+    points: number
+}
+
+export interface ComponentValuation {
+    kind: 'component'
+    rawMass: number
+    processedMass: number
+    weight: number
+    quality: number
+    baseAtomic: bigint
+    effortAtomic: bigint
+    totalAtomic: bigint
+    points: number
+}
+
+export type CargoValuation = ResourceValuation | ComponentValuation
+
+export function explainCargoItem(
+    item: ValuedItem,
+    demand: DemandView,
+    pricing: InfluencePricing
+): CargoValuation {
+    const def = getItem(item.itemId)
+    const totalAtomic = valueCargoItem(item, demand, pricing)
+    const points = Number(totalAtomic) / INFLUENCE_ATOMIC_PER_POINT
+    const nStats = getStatCount(item.itemId)
+    const quality = statsSumSq(item.stats, nStats) / (nStats * pricing.d1)
+
+    if (def.type === 'resource') {
+        if (def.category === undefined) throw new Error('resource has no category')
+        const category = categoryIndex(def.category)
+        return {
+            kind: 'resource',
+            category,
+            tier: def.tier,
+            mass: BigInt(def.mass) * BigInt(item.quantity),
+            weight: Number(pricing.weight(category, def.tier)) / WEIGHT_FP_SCALE,
+            quality,
+            need: Number(needForCategory(demand, category)) / NEED_FP_SCALE,
+            totalAtomic,
+            points,
+        }
+    }
+
+    const entry = findDecomp(item.itemId)
+    if (!entry) throw new Error('item has no decomposition')
+    let rawMass = 0
+    let weighted = 0n
+    for (const bucket of entry.buckets) {
+        rawMass += bucket.rawMass
+        weighted += BigInt(bucket.rawMass) * pricing.weight(bucket.category, bucket.tier)
+    }
+    const effortAtomic = componentEffortAtomic(entry.processedMass, item.quantity)
+    return {
+        kind: 'component',
+        rawMass: rawMass * item.quantity,
+        processedMass: entry.processedMass * item.quantity,
+        weight: rawMass === 0 ? 0 : Number(weighted) / (rawMass * WEIGHT_FP_SCALE),
+        quality,
+        baseAtomic: totalAtomic - effortAtomic,
+        effortAtomic,
+        totalAtomic,
+        points,
+    }
+}
+
 export function valueContribution(
     bundle: ValuedItem[],
     demand: DemandView,

package/src/managers/actions.ts

@@ -332,25 +332,35 @@ export class ActionsManager extends BaseManager {
     depotstore(
         shipId: UInt64Type,
         depotId: UInt64Type,
-        items: ServerContract.ActionParams.Type.cargo_item[]
+        items: ServerContract.ActionParams.Type.cargo_item[],
+        shuttledBy?: UInt64Type
     ): Action {
-        return this.server.action('depotstore', {
+        const params: ServerContract.ActionParams.depotstore = {
             ship_id: UInt64.from(shipId),
             depot_id: UInt64.from(depotId),
             items,
-        })
+        }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
+        return this.server.action('depotstore', params)
     }
 
     depottake(
         shipId: UInt64Type,
         depotId: UInt64Type,
-        items: ServerContract.ActionParams.Type.cargo_item[]
+        items: ServerContract.ActionParams.Type.cargo_item[],
+        shuttledBy?: UInt64Type
     ): Action {
-        return this.server.action('depottake', {
+        const params: ServerContract.ActionParams.depottake = {
             ship_id: UInt64.from(shipId),
             depot_id: UInt64.from(depotId),
             items,
-        })
+        }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
+        return this.server.action('depottake', params)
     }
 
     shuttle(
@@ -518,7 +528,8 @@ export class ActionsManager extends BaseManager {
         workshopId: UInt64Type,
         recipeId: UInt16Type,
         quantity: UInt32Type,
-        inputs: ServerContract.ActionParams.Type.cargo_item[]
+        inputs: ServerContract.ActionParams.Type.cargo_item[],
+        shuttledBy?: UInt64Type
     ): Action {
         const params: ServerContract.ActionParams.craftjob = {
             ship_id: UInt64.from(shipId),
@@ -527,6 +538,9 @@ export class ActionsManager extends BaseManager {
             quantity: UInt32.from(quantity),
             inputs,
         }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
         return this.server.action('craftjob', params)
     }
 
@@ -540,6 +554,9 @@ export class ActionsManager extends BaseManager {
     canceljob(route: JobCancelRoute): Action {
         if (route.kind === 'dropoff') return this.cancel(route.shipId, route.laneKey, route.count)
         if (route.kind === 'build') return this.cancelbuild(route.jobId)
+        if (route.kind === 'civic') {
+            return this.cancelcivic(route.buildingId, route.laneKey, route.fromId)
+        }
         return this.cancelcraft(route.jobId)
     }
 
@@ -566,11 +583,14 @@ export class ActionsManager extends BaseManager {
         return this.server.action('clustercraft', params)
     }
 
-    claimcraft(jobId: UInt64Type, shipId: UInt64Type): Action {
+    claimcraft(jobId: UInt64Type, shipId: UInt64Type, shuttledBy?: UInt64Type): Action {
         const params: ServerContract.ActionParams.claimcraft = {
             job_id: UInt64.from(jobId),
             ship_id: UInt64.from(shipId),
         }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
         return this.server.action('claimcraft', params)
     }
 
@@ -578,7 +598,8 @@ export class ActionsManager extends BaseManager {
         targetId: UInt64Type,
         dockId: UInt64Type,
         targetItemId: UInt16Type,
-        inputs: ServerContract.ActionParams.Type.cargo_item[]
+        inputs: ServerContract.ActionParams.Type.cargo_item[],
+        shuttledBy?: UInt64Type
     ): Action {
         const params: ServerContract.ActionParams.buildjob = {
             target_id: UInt64.from(targetId),
@@ -586,6 +607,9 @@ export class ActionsManager extends BaseManager {
             target_item_id: UInt16.from(targetItemId),
             inputs,
         }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
         return this.server.action('buildjob', params)
     }
 
@@ -596,10 +620,13 @@ export class ActionsManager extends BaseManager {
         return this.server.action('claimbuild', params)
     }
 
-    cancelbuild(jobId: UInt64Type): Action {
+    cancelbuild(jobId: UInt64Type, shuttledBy?: UInt64Type): Action {
         const params: ServerContract.ActionParams.cancelbuild = {
             job_id: UInt64.from(jobId),
         }
+        if (shuttledBy !== undefined) {
+            params.shuttled_by = UInt64.from(shuttledBy)
+        }
         return this.server.action('cancelbuild', params)
     }
 
@@ -610,6 +637,18 @@ export class ActionsManager extends BaseManager {
         })
     }
 
+    blenddepot(
+        depotId: UInt64Type,
+        owner: NameType,
+        inputs: ServerContract.ActionParams.Type.cargo_item[]
+    ): Action {
+        return this.server.action('blenddepot', {
+            depot_id: UInt64.from(depotId),
+            owner: Name.from(owner),
+            inputs,
+        })
+    }
+
     deploy(
         entityId: UInt64Type,
         ref: ServerContract.ActionParams.Type.cargo_ref,

package/src/managers/balances.test.ts

@@ -78,6 +78,39 @@ describe('getDepositConfig', () => {
     })
 })
 
+describe('setDepositConfig', () => {
+    test('a seeded config keeps every balance read off the chain', async () => {
+        const {manager, counts} = stubContext({
+            depositConfig: SCRAP,
+            balances: [{token_contract: 'scrap.gm', balance: '5 SCRAP'}],
+            wallet: ['7 SCRAP'],
+        })
+        manager.setDepositConfig({tokenContract: 'scrap.gm', symbol: '0,SCRAP'})
+
+        const config = await manager.getDepositConfig()
+        expect(String(config?.tokenContract)).toBe('scrap.gm')
+        expect(String(config?.symbol)).toBe('0,SCRAP')
+        await manager.getPlatformBalance('alice')
+        await manager.getWalletBalance('alice')
+
+        expect(counts.depositcfg).toBe(0)
+    })
+
+    test('a reload still reaches the chain', async () => {
+        const {manager, counts} = stubContext({depositConfig: SCRAP})
+        manager.setDepositConfig({tokenContract: 'scrap.gm', symbol: '0,SCRAP'})
+        await manager.getDepositConfig(true)
+        expect(counts.depositcfg).toBe(1)
+    })
+
+    test('seeding null records a chain with no deposit token', async () => {
+        const {manager, counts} = stubContext({depositConfig: SCRAP})
+        manager.setDepositConfig(null)
+        expect(await manager.getDepositConfig()).toBeNull()
+        expect(counts.depositcfg).toBe(0)
+    })
+})
+
 describe('getPlatformBalance', () => {
     test('returns null when the owner has never opened a row', async () => {
         const {manager} = stubContext({depositConfig: SCRAP, balances: []})

package/src/managers/balances.ts

@@ -7,6 +7,11 @@ export interface DepositConfig {
     symbol: Asset.Symbol
 }
 
+export interface DepositConfigInput {
+    tokenContract: NameType
+    symbol: Asset.SymbolType
+}
+
 export interface PlatformBalance {
     owner: Name
     tokenContract: Name
@@ -22,6 +27,16 @@ export interface TokenBalance {
 export class BalancesManager extends BaseManager {
     private depositConfig?: DepositConfig | null
 
+    // A caller holding the config already, from the indexer or its own cache, seeds it here so no balance read reaches the chain for it.
+    setDepositConfig(config: DepositConfigInput | null): void {
+        this.depositConfig = config
+            ? {
+                  tokenContract: Name.from(config.tokenContract),
+                  symbol: Asset.Symbol.from(config.symbol),
+              }
+            : null
+    }
+
     async getDepositConfig(reload = false): Promise<DepositConfig | null> {
         if (!reload && this.depositConfig !== undefined) {
             return this.depositConfig

package/src/managers/context.ts

@@ -15,6 +15,7 @@ import {NftManager} from './nft'
 import {BalancesManager} from './balances'
 import {FundManager} from './fund'
 import {JobsManager} from './jobs'
+import {ShuttleManager} from './shuttle'
 import {InfluenceManager} from './influence'
 import {SubscriptionsManager} from '../subscriptions/manager'
 
@@ -30,12 +31,15 @@ export class GameContext {
     private _balances?: BalancesManager
     private _funds?: FundManager
     private _jobs?: JobsManager
+    private _shuttle?: ShuttleManager
     private _influence?: InfluenceManager
     private _subscriptions?: SubscriptionsManager
     private _subscriptionsUrl?: string
 
     private _gameCache?: PlatformContract.Types.game_row
+    private _gameInflight?: Promise<PlatformContract.Types.game_row>
     private _stateCache?: GameState
+    private _stateInflight?: Promise<GameState>
 
     constructor(
         public readonly client: APIClient,
@@ -122,6 +126,13 @@ export class GameContext {
         return this._jobs
     }
 
+    get shuttle(): ShuttleManager {
+        if (!this._shuttle) {
+            this._shuttle = new ShuttleManager(this)
+        }
+        return this._shuttle
+    }
+
     get influence(): InfluenceManager {
         if (!this._influence) {
             this._influence = new InfluenceManager(this)
@@ -149,25 +160,53 @@ export class GameContext {
         if (!reload && this._gameCache) {
             return this._gameCache
         }
-        const game = await this.platform.table('games').get()
-        if (!game) {
-            throw new Error('Game not initialized')
+        if (!reload && this._gameInflight) {
+            return this._gameInflight
+        }
+        const inflight = (async () => {
+            const game = await this.platform.table('games').get()
+            if (!game) {
+                throw new Error('Game not initialized')
+            }
+            this._gameCache = game
+            return game
+        })()
+        this._gameInflight = inflight
+        try {
+            return await inflight
+        } finally {
+            if (this._gameInflight === inflight) {
+                this._gameInflight = undefined
+            }
         }
-        this._gameCache = game
-        return game
     }
 
     async getState(reload = false): Promise<GameState> {
         if (!reload && this._stateCache) {
             return this._stateCache
         }
-        const state = await this.server.table('state').get()
-        if (!state) {
-            throw new Error('Game state not initialized')
+        if (!reload && this._stateInflight) {
+            return this._stateInflight
+        }
+        const inflight = (async () => {
+            const [state, game] = await Promise.all([
+                this.server.table('state').get(),
+                this.getGame(),
+            ])
+            if (!state) {
+                throw new Error('Game state not initialized')
+            }
+            this._stateCache = GameState.from(state, game)
+            return this._stateCache
+        })()
+        this._stateInflight = inflight
+        try {
+            return await inflight
+        } finally {
+            if (this._stateInflight === inflight) {
+                this._stateInflight = undefined
+            }
         }
-        const game = this._gameCache
-        this._stateCache = GameState.from(state, game)
-        return this._stateCache
     }
 
     get cachedGame(): PlatformContract.Types.game_row | undefined {

package/src/managers/index.ts

@@ -15,6 +15,20 @@ export type {NftConfigForItem, WrapConfig, WrapGate} from './nft'
 export {BalancesManager} from './balances'
 export type {DepositConfig, PlatformBalance, TokenBalance} from './balances'
 export {JobsManager} from './jobs'
+export {
+    ShuttleManager,
+    rankShuttleOptions,
+    shuttleReasonCode,
+    BOOKING_LEVEL_CODES,
+    OMITTED_REASONS,
+} from './shuttle'
+export type {
+    ShuttleMode,
+    ShuttleOption,
+    ShuttleOptions,
+    ShuttleReason,
+    ShuttleReasonCode,
+} from './shuttle'
 export {InfluenceManager} from './influence'
 export type {
     CharterProgress,