@shipload/sdk 1.0.0-next.42 → 1.0.0-next.43

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@shipload/sdk",
     "description": "SDKs for Shipload",
-    "version": "1.0.0-next.42",
+    "version": "1.0.0-next.43",
     "homepage": "https://github.com/shipload/toolkit/tree/master/packages/sdk",
     "repository": {
         "type": "git",

package/src/data/capabilities.ts

@@ -8,6 +8,14 @@ export interface StatMapping {
     stat: string
     capability: string
     attribute: string
+    source: string // producing module/role, always present
+}
+
+export interface CapabilityAttributeRow {
+    capability: string
+    attribute: string
+    description: string
+    source?: string // producing module/role; absent when no formula-derived producer exists
 }
 
 export const capabilityNames: string[] = [

package/src/data/recipes.json

@@ -875,147 +875,5 @@
       }
     ],
     "blendWeights": []
-  },
-  {
-    "outputItemId": 20001,
-    "outputMass": 500,
-    "inputs": [
-      {
-        "itemId": 10001,
-        "quantity": 200
-      },
-      {
-        "itemId": 102,
-        "quantity": 15
-      }
-    ],
-    "statSlots": [
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 0
-          },
-          {
-            "inputIndex": 1,
-            "statIndex": 0
-          }
-        ]
-      },
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 1
-          },
-          {
-            "inputIndex": 1,
-            "statIndex": 2
-          }
-        ]
-      }
-    ],
-    "blendWeights": [
-      1,
-      1
-    ]
-  },
-  {
-    "outputItemId": 20002,
-    "outputMass": 300,
-    "inputs": [
-      {
-        "itemId": 10002,
-        "quantity": 200
-      },
-      {
-        "itemId": 402,
-        "quantity": 10
-      },
-      {
-        "itemId": 502,
-        "quantity": 20
-      }
-    ],
-    "statSlots": [
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 0
-          },
-          {
-            "inputIndex": 1,
-            "statIndex": 1
-          }
-        ]
-      },
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 1
-          },
-          {
-            "inputIndex": 2,
-            "statIndex": 2
-          }
-        ]
-      }
-    ],
-    "blendWeights": [
-      1,
-      1,
-      1
-    ]
-  },
-  {
-    "outputItemId": 20200,
-    "outputMass": 80000,
-    "inputs": [
-      {
-        "itemId": 20001,
-        "quantity": 600
-      },
-      {
-        "itemId": 20002,
-        "quantity": 200
-      }
-    ],
-    "statSlots": [
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 0
-          }
-        ]
-      },
-      {
-        "sources": [
-          {
-            "inputIndex": 0,
-            "statIndex": 1
-          }
-        ]
-      },
-      {
-        "sources": [
-          {
-            "inputIndex": 1,
-            "statIndex": 0
-          }
-        ]
-      },
-      {
-        "sources": [
-          {
-            "inputIndex": 1,
-            "statIndex": 1
-          }
-        ]
-      }
-    ],
-    "blendWeights": []
   }
 ]

package/src/derivation/capability-mappings.ts

@@ -18,7 +18,8 @@ import {
     ITEM_WAREHOUSE_T1_PACKED,
     ITEM_CONTAINER_T2_PACKED,
 } from '../data/item-ids'
-import type {StatMapping} from '../data/capabilities'
+import type {StatMapping, CapabilityAttributeRow} from '../data/capabilities'
+import {capabilityAttributes} from '../data/capabilities'
 
 export const KIND_TO_ITEM_ID: Record<SlotConsumerKind, number> = {
     engine: ITEM_ENGINE_T1,
@@ -69,6 +70,12 @@ function traceToRawCategoryStat(
     return traceToRawCategoryStat(subRecipe, subSource, nextVisited)
 }
 
+// Producing role for a capability·attribute: entity hull slots all roll up to "Hull"; modules use their own name.
+export function sourceLabelForOutput(itemId: number): string {
+    const item = getItem(itemId)
+    return item.type === 'entity' ? 'Hull' : item.name
+}
+
 let cached: StatMapping[] | undefined
 
 export function deriveStatMappings(): StatMapping[] {
@@ -82,20 +89,22 @@ export function deriveStatMappings(): StatMapping[] {
         const itemId = KIND_TO_ITEM_ID[kind]
         const recipe = getRecipe(itemId)
         if (!recipe) continue
+        const source = sourceLabelForOutput(itemId)
         for (const [slotIdxStr, consumer] of Object.entries(slots)) {
             const slotIdx = Number(slotIdxStr)
             const slot = recipe.statSlots[slotIdx]
             if (!slot) continue
-            for (const source of slot.sources) {
-                const stat = traceToRawCategoryStat(recipe, source)
+            for (const src of slot.sources) {
+                const stat = traceToRawCategoryStat(recipe, src)
                 if (!stat) continue
-                const key = `${stat.label}|${consumer.capability}|${consumer.attribute}`
+                const key = `${stat.label}|${consumer.capability}|${consumer.attribute}|${source}`
                 if (seen.has(key)) continue
                 seen.add(key)
                 out.push({
                     stat: stat.label,
                     capability: consumer.capability,
                     attribute: consumer.attribute,
+                    source,
                 })
             }
         }
@@ -115,3 +124,39 @@ export function getStatMappingsForStat(stat: string): StatMapping[] {
 export function getStatMappingsForCapability(capability: string): StatMapping[] {
     return deriveStatMappings().filter((m) => m.capability === capability)
 }
+
+export function getProducersForAttribute(capability: string, attribute: string): string[] {
+    const seen = new Set<string>()
+    const out: string[] = []
+    for (const m of deriveStatMappings()) {
+        if (m.capability !== capability || m.attribute !== attribute) continue
+        if (seen.has(m.source)) continue
+        seen.add(m.source)
+        out.push(m.source)
+    }
+    return out
+}
+
+export function getCapabilityAttributeRows(): CapabilityAttributeRow[] {
+    const rows: CapabilityAttributeRow[] = []
+    for (const ca of capabilityAttributes) {
+        const producers = getProducersForAttribute(ca.capability, ca.attribute)
+        if (producers.length === 0) {
+            rows.push({
+                capability: ca.capability,
+                attribute: ca.attribute,
+                description: ca.description,
+            })
+            continue
+        }
+        for (const source of producers) {
+            rows.push({
+                capability: ca.capability,
+                attribute: ca.attribute,
+                description: ca.description,
+                source,
+            })
+        }
+    }
+    return rows
+}

package/src/index-module.ts

@@ -283,6 +283,17 @@ export type {
     CancelEligibilityInput,
 } from './scheduling/cancel'
 
+export {
+    derivedLoaders,
+    estimateUnwrapDuration,
+    incomingHoldMass,
+    projectedPeakCargomass,
+    receiveFits,
+    unwrapLoadDuration,
+    unwrapTransitDuration,
+} from './scheduling/unwrap'
+export type {DerivedLoaders, UnwrapDestination, UnwrapItem} from './scheduling/unwrap'
+
 export {
     projectedCargoAvailableAt,
     availableForItem,
@@ -348,13 +359,16 @@ export {
     isInvertedAttribute,
     getCapabilityAttributes,
 } from './data/capabilities'
-export type {CapabilityAttribute, StatMapping} from './data/capabilities'
+export type {CapabilityAttribute, StatMapping, CapabilityAttributeRow} from './data/capabilities'
 
 export {
     deriveStatMappings,
     getStatMappings,
     getStatMappingsForStat,
     getStatMappingsForCapability,
+    getProducersForAttribute,
+    getCapabilityAttributeRows,
+    sourceLabelForOutput,
 } from './derivation/capability-mappings'
 export {SLOT_FORMULAS} from './data/capability-formulas'
 export type {SlotConsumer, SlotConsumerKind} from './data/capability-formulas'
@@ -422,6 +436,7 @@ export {
     feistelInv,
     regionOf,
     partnerRegion,
+    nearbyWormholes,
     wormholeAt,
     wormholeAtRegionEndpoint,
     isValidWormholePair,

package/src/managers/actions.ts

@@ -593,6 +593,23 @@ export class ActionsManager extends BaseManager {
         )
     }
 
+    sendAsset(owner: NameType, recipient: NameType, assetId: UInt64Type, memo = ''): Action {
+        return Action.from(
+            {
+                account: this.atomicAssetsAccount,
+                name: 'transfer',
+                authorization: [{actor: Name.from(owner), permission: 'active'}],
+                data: {
+                    from: Name.from(owner),
+                    to: Name.from(recipient),
+                    asset_ids: [UInt64.from(assetId)],
+                    memo,
+                },
+            },
+            ATOMICASSETS_ABI
+        )
+    }
+
     // Two top-level actions the wallet signs to unwrap an NFT into a host's cargo.
     unwrapCargoTx(owner: NameType, assetId: UInt64Type, hostId: UInt64Type): Action[] {
         return [this.transferForUnwrap(owner, assetId), this.placecargo(owner, hostId, assetId)]

package/src/scheduling/unwrap.test.ts

@@ -0,0 +1,60 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    derivedLoaders,
+    unwrapTransitDuration,
+    unwrapLoadDuration,
+    estimateUnwrapDuration,
+    incomingHoldMass,
+    projectedPeakCargomass,
+} from './unwrap'
+
+describe('unwrap duration mirror', () => {
+    test('derivedLoaders aggregates lanes like derived_loaders()', () => {
+        expect(derivedLoaders([])).toBeNull()
+        expect(
+            derivedLoaders([
+                {mass: 1000, thrust: 10},
+                {mass: 1400, thrust: 20},
+            ])
+        ).toEqual({mass: 1200, thrust: 30, quantity: 2}) // floor(2400/2)=1200, sum thrust, count
+    })
+
+    test('transit floors distance then flight time', () => {
+        // distance = floor(sqrt(3^2+4^2)*10000)=50000; accel=400/mass*10000; flight=floor(2*sqrt(d/accel))
+        const mass = 1000
+        const accel = (400 / mass) * 10000
+        const expected = Math.floor(2 * Math.sqrt(50000 / accel))
+        expect(unwrapTransitDuration(mass, {x: 0, y: 0}, {x: 3, y: 4})).toBe(expected)
+    })
+
+    test('load uses altitude z, adds loader mass, divides by quantity', () => {
+        const loaders = {mass: 1200, thrust: 30, quantity: 2}
+        const itemMass = 800
+        const accel = (30 / (itemMass + 1200)) * 10000
+        const flight = Math.floor(2 * Math.sqrt(3000 / accel))
+        expect(unwrapLoadDuration(loaders, itemMass, 3000)).toBe(Math.floor(flight / 2))
+    })
+
+    test('zero item mass and no loaders are safe', () => {
+        expect(unwrapTransitDuration(0, {x: 0, y: 0}, {x: 9, y: 9})).toBe(0)
+        expect(unwrapLoadDuration(null, 500, 3000)).toBe(0)
+    })
+})
+
+test('incomingHoldMass sums incoming-kind hold mass', () => {
+    expect(incomingHoldMass([])).toBe(0)
+    // PUSH(2) + FLIGHT(5) count; BUILD(4) does not
+    expect(
+        incomingHoldMass([
+            {kind: 2, incoming_mass: 100},
+            {kind: 4, incoming_mass: 999},
+            {kind: 5, incoming_mass: 50},
+        ])
+    ).toBe(150)
+})
+
+test('projectedPeakCargomass tracks the running peak from cargomass', () => {
+    const entity = {cargomass: 1000, lanes: [], cargo: [], schedule: undefined} as never
+    // No pending tasks: peak = base + candidate add.
+    expect(projectedPeakCargomass(entity, new Date(0), 500)).toBe(1500)
+})

package/src/scheduling/unwrap.ts

@@ -0,0 +1,187 @@
+import type {UInt16Type, UInt32Type} from '@wharfkit/antelope'
+import {calcCargoItemMass} from '../capabilities/storage'
+import type {ServerContract} from '../contracts'
+import {PRECISION} from '../types'
+import * as sched from './schedule'
+import {taskCargoEffect} from './availability'
+import {candidateLaneCompletesAt} from './lanes'
+
+const NFT_TRANSIT_THRUST = 400
+
+export interface DerivedLoaders {
+    mass: number
+    thrust: number
+    quantity: number
+}
+
+export function derivedLoaders(
+    lanes: {mass: UInt32Type | number; thrust: UInt16Type | number}[] | undefined
+): DerivedLoaders | null {
+    if (!lanes || lanes.length === 0) return null
+    let totalMass = 0
+    let totalThrust = 0
+    for (const l of lanes) {
+        totalMass += Number(l.mass)
+        totalThrust += Number(l.thrust)
+    }
+    const count = lanes.length
+    return {
+        mass: Math.floor(totalMass / count),
+        thrust: Math.min(totalThrust, 65_535),
+        quantity: count,
+    }
+}
+
+function acceleration(thrust: number, mass: number): number {
+    if (mass <= 0) return 0
+    return (thrust / mass) * PRECISION
+}
+
+function flightTime(distance: number, accel: number): number {
+    if (accel <= 0 || distance <= 0) return 0
+    return Math.floor(2 * Math.sqrt(distance / accel))
+}
+
+function distance2d(ax: number, ay: number, bx: number, by: number): number {
+    const dx = ax - bx
+    const dy = ay - by
+    return Math.floor(Math.sqrt(dx * dx + dy * dy) * PRECISION)
+}
+
+export function unwrapTransitDuration(
+    itemMass: number,
+    origin: {x: number; y: number},
+    dest: {x: number; y: number}
+): number {
+    if (itemMass <= 0) return 0
+    return flightTime(
+        distance2d(origin.x, origin.y, dest.x, dest.y),
+        acceleration(NFT_TRANSIT_THRUST, itemMass)
+    )
+}
+
+export function unwrapLoadDuration(
+    loaders: DerivedLoaders | null,
+    itemMass: number,
+    destZ: number
+): number {
+    if (!loaders || itemMass <= 0) return 0
+    const total = itemMass + loaders.mass
+    const flight = flightTime(destZ, acceleration(loaders.thrust, total))
+    return Math.floor(flight / loaders.quantity)
+}
+
+export interface UnwrapItem {
+    itemId: number
+    quantity: number
+    modules: ServerContract.Types.module_entry[]
+    originX: number
+    originY: number
+}
+
+export interface UnwrapDestination {
+    loader_lanes?: {mass: UInt32Type | number; thrust: UInt16Type | number}[]
+    coordinates: {x: UInt32Type | number; y: UInt32Type | number; z?: UInt32Type | number}
+}
+
+export function estimateUnwrapDuration(dest: UnwrapDestination, item: UnwrapItem): number {
+    const itemMass = Number(
+        calcCargoItemMass({
+            item_id: item.itemId as never,
+            quantity: item.quantity as never,
+            modules: item.modules,
+        })
+    )
+    const loaders = derivedLoaders(dest.loader_lanes)
+    const dz = Number(dest.coordinates.z ?? 0)
+    const load = unwrapLoadDuration(loaders, itemMass, dz)
+    const transit = unwrapTransitDuration(
+        itemMass,
+        {x: item.originX, y: item.originY},
+        {
+            x: Number(dest.coordinates.x),
+            y: Number(dest.coordinates.y),
+        }
+    )
+    return load + transit
+}
+
+// Hold kinds that count as incoming (mirror is_incoming_hold_kind in holds.hpp).
+const INCOMING_HOLD_KINDS = new Set<number>([2, 3, 5])
+
+export function incomingHoldMass(
+    holds:
+        | {kind: number | {toNumber(): number}; incoming_mass: number | {toNumber(): number}}[]
+        | undefined
+): number {
+    if (!holds) return 0
+    let total = 0
+    for (const h of holds) {
+        if (INCOMING_HOLD_KINDS.has(Number(h.kind))) total += Number(h.incoming_mass)
+    }
+    return total
+}
+
+type CargoItem = ServerContract.Types.cargo_item
+
+function cargoListMass(items: CargoItem[]): number {
+    let m = 0
+    for (const it of items) m += Number(calcCargoItemMass(it))
+    return m
+}
+
+export function projectedPeakCargomass(
+    entity: sched.ScheduleData & {cargomass: number | {toNumber(): number}},
+    at: Date,
+    addMass: number,
+    removeMass = 0
+): number {
+    const events: {t: number; delta: number}[] = []
+    for (const ordered of sched.orderedTasks(entity)) {
+        const eff = taskCargoEffect(ordered.task)
+        const delta = cargoListMass(eff.added) - cargoListMass(eff.removed)
+        events.push({t: ordered.completesAt.getTime(), delta})
+    }
+    events.push({t: at.getTime(), delta: addMass - removeMass})
+    events.sort((a, b) => (a.t !== b.t ? a.t - b.t : b.delta - a.delta))
+    let running = Number(entity.cargomass)
+    let peak = running
+    for (const e of events) {
+        running += e.delta
+        if (running < 0) running = 0
+        if (running > peak) peak = running
+    }
+    return Math.min(peak, 0xffff_ffff)
+}
+
+export function receiveFits(
+    dest: UnwrapDestination &
+        sched.ScheduleData & {
+            cargomass: number | {toNumber(): number}
+            capacity?: number | {toNumber(): number}
+            holds?: {
+                kind: number | {toNumber(): number}
+                incoming_mass: number | {toNumber(): number}
+            }[]
+        },
+    item: UnwrapItem,
+    now: Date
+): boolean {
+    const capacity = Number(dest.capacity ?? 0)
+    if (capacity <= 0) return false
+    const itemMass = Number(
+        calcCargoItemMass({
+            item_id: item.itemId as never,
+            quantity: item.quantity as never,
+            modules: item.modules,
+        })
+    )
+    const duration = estimateUnwrapDuration(dest, item)
+    const candidateCompletes = candidateLaneCompletesAt(dest, sched.LANE_MOBILITY, duration, now)
+    const peak = projectedPeakCargomass(
+        dest,
+        candidateCompletes,
+        itemMass + incomingHoldMass(dest.holds)
+    )
+    return peak <= capacity
+}