@shipload/sdk 1.0.0-next.2 → 1.0.0-next.21

package/src/derivation/capabilities.ts

@@ -0,0 +1,414 @@
+export function computeBaseHullmass(stats: Record<string, number>): number {
+    return 100000 - 75 * stats.density
+}
+
+export function computeShipHullCapabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const statSum = stats.strength + stats.hardness + stats.saturation
+    const exponent = statSum / 2997.0
+    return {
+        hullmass: computeBaseHullmass(stats),
+        capacity: Math.floor(5000000 * 6 ** exponent),
+    }
+}
+
+export function computeEngineCapabilities(stats: Record<string, number>): {
+    thrust: number
+    drain: number
+} {
+    const vol = stats.volatility
+    const thm = stats.thermal
+
+    return {
+        thrust: 400 + Math.floor((vol * 3) / 4),
+        drain: Math.max(30, 50 - Math.floor(thm / 70)),
+    }
+}
+
+export function computeGeneratorCapabilities(stats: Record<string, number>): {
+    capacity: number
+    recharge: number
+} {
+    const res = stats.resonance
+    const ref = stats.reflectivity
+
+    return {
+        capacity: 300 + Math.floor(res / 6),
+        recharge: 1 + Math.floor((ref * 3) / 1000),
+    }
+}
+
+export interface GathererDepthParams {
+    readonly floor: number
+    readonly slope: number
+}
+
+export const GATHERER_DEPTH_TABLE: readonly GathererDepthParams[] = [
+    {floor: 500, slope: 5},
+    {floor: 2000, slope: 11},
+    {floor: 7000, slope: 16},
+    {floor: 15000, slope: 18},
+    {floor: 25000, slope: 19},
+    {floor: 35000, slope: 16},
+    {floor: 46000, slope: 12},
+    {floor: 53500, slope: 10},
+    {floor: 60000, slope: 5},
+    {floor: 63500, slope: 2},
+]
+
+export const GATHERER_DEPTH_MAX_TIER = 10
+
+export function gathererDepthForTier(tol: number, tier: number): number {
+    if (tier < 1 || tier > GATHERER_DEPTH_MAX_TIER) {
+        throw new Error(`gatherer tier out of range: ${tier}`)
+    }
+    const p = GATHERER_DEPTH_TABLE[tier - 1]
+    return p.floor + tol * p.slope
+}
+
+export function computeGathererCapabilities(
+    stats: Record<string, number>,
+    tier: number
+): {
+    yield: number
+    drain: number
+    depth: number
+} {
+    const str = stats.strength
+    const con = stats.conductivity
+    const tol = stats.tolerance
+
+    return {
+        yield: 200 + str,
+        drain: Math.max(250, 1250 - Math.floor((con * 25) / 20)),
+        depth: gathererDepthForTier(tol, tier),
+    }
+}
+
+export function computeLoaderCapabilities(stats: Record<string, number>): {
+    mass: number
+    thrust: number
+    quantity: number
+} {
+    const insulation = stats.insulation
+    const plasticity = stats.plasticity
+
+    return {
+        mass: Math.max(200, 2000 - Math.floor(insulation * 2)),
+        thrust: 1 + Math.floor(plasticity / 500),
+        quantity: 1,
+    }
+}
+
+export function computeCrafterCapabilities(stats: Record<string, number>): {
+    speed: number
+    drain: number
+} {
+    const rea = stats.reactivity
+    const fin = stats.fineness
+
+    return {
+        speed: 100 + Math.floor((rea * 4) / 5),
+        drain: Math.max(5, 30 - Math.floor(fin / 33)),
+    }
+}
+
+export function computeHaulerCapabilities(stats: Record<string, number>): {
+    capacity: number
+    efficiency: number
+    drain: number
+} {
+    const resonance = stats.resonance
+    const conductivity = stats.conductivity
+    const reflectivity = stats.reflectivity
+
+    return {
+        capacity: Math.max(1, 1 + Math.floor(resonance / 400)),
+        efficiency: 2000 + conductivity * 6,
+        drain: Math.max(3, 15 - Math.floor(reflectivity / 80)),
+    }
+}
+
+export function computeStorageCapabilities(
+    stats: Record<string, number>,
+    baseCapacity: number
+): {
+    capacityBonus: number
+} {
+    const strength = stats.strength
+    const density = stats.density
+    const hardness = stats.hardness
+    const saturation = stats.saturation
+
+    const statSum = strength + density + hardness + saturation
+    const capacityBonus = Math.floor(
+        (baseCapacity * (10 + Math.floor((statSum * 10) / 2997))) / 100
+    )
+
+    return {capacityBonus}
+}
+
+import {
+    ITEM_CONTAINER_T1_PACKED,
+    ITEM_CONTAINER_T2_PACKED,
+    ITEM_EXTRACTOR_T1_PACKED,
+    ITEM_FACTORY_T1_PACKED,
+    ITEM_SHIP_T1_PACKED,
+    ITEM_WAREHOUSE_T1_PACKED,
+} from '../data/item-ids'
+import {
+    getModuleCapabilityType,
+    MODULE_BATTERY,
+    MODULE_ENGINE,
+    MODULE_GENERATOR,
+    MODULE_GATHERER,
+    MODULE_LOADER,
+    MODULE_STORAGE,
+    MODULE_CRAFTER,
+    MODULE_HAULER,
+    MODULE_WARP,
+} from '../capabilities/modules'
+import {getItem} from '../data/catalog'
+import {decodeCraftedItemStats} from './crafting'
+import {
+    applySlotMultiplier,
+    clampUint16,
+    getSlotAmp,
+    type InstalledModule,
+} from '../entities/slot-multiplier'
+import type {EntitySlot} from '../data/recipes-runtime'
+
+export function computeBaseCapacity(itemId: number, stats: Record<string, number>): number {
+    switch (itemId) {
+        case ITEM_SHIP_T1_PACKED:
+        case ITEM_EXTRACTOR_T1_PACKED:
+        case ITEM_FACTORY_T1_PACKED:
+            return computeShipHullCapabilities(stats).capacity
+        case ITEM_CONTAINER_T1_PACKED:
+            return computeContainerCapabilities(stats).capacity
+        case ITEM_WAREHOUSE_T1_PACKED:
+            return computeWarehouseHullCapabilities(stats).capacity
+        case ITEM_CONTAINER_T2_PACKED:
+            return computeContainerT2Capabilities(stats).capacity
+        default:
+            return 0
+    }
+}
+
+export function computeWarpCapabilities(stats: Record<string, number>): {
+    range: number
+} {
+    const res = stats.resonance
+    return {range: 100 + res * 3}
+}
+
+export function computeWarehouseHullCapabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const statSum = stats.strength + stats.hardness + stats.saturation
+    const exponent = statSum / 2997.0
+    return {
+        hullmass: computeBaseHullmass(stats),
+        capacity: Math.floor(100000000 * 6 ** exponent),
+    }
+}
+
+export interface ComputedCapabilities {
+    hullmass: number
+    capacity: number
+    engines?: {thrust: number; drain: number}
+    generator?: {capacity: number; recharge: number}
+    gatherer?: {yield: number; drain: number; depth: number}
+    loaders?: {mass: number; thrust: number; quantity: number}
+    crafter?: {speed: number; drain: number}
+    hauler?: {capacity: number; efficiency: number; drain: number}
+    warp?: {range: number}
+}
+
+export function computeEntityCapabilities(
+    stats: Record<string, number>,
+    itemId: number,
+    modules: InstalledModule[],
+    layout: EntitySlot[]
+): ComputedCapabilities {
+    let totalThrust = 0
+    let totalEngineDrain = 0
+    let hasEngine = false
+
+    let totalGenCapacity = 0
+    let totalGenRecharge = 0
+    let hasGenerator = false
+
+    let totalLoaderMass = 0
+    let totalLoaderThrust = 0
+    let totalLoaderQuantity = 0
+    let hasLoader = false
+
+    let totalGathYield = 0
+    let totalGathDrain = 0
+    let maxGathDepth = 0
+    let hasGatherer = false
+
+    let totalStorageBonus = 0
+    const baseCapacity = computeBaseCapacity(itemId, stats)
+    let installedModuleMass = 0
+
+    let totalCrafterSpeed = 0
+    let totalCrafterDrain = 0
+    let hasCrafter = false
+
+    let totalHaulerCapacity = 0
+    let weightedHaulerEffNum = 0n
+    let totalHaulerDrain = 0
+    let hasHauler = false
+
+    let totalWarpRange = 0
+    let hasWarp = false
+
+    let totalBatteryStatSum = 0
+    let batteryCount = 0
+
+    for (const mod of modules) {
+        const item = getItem(mod.itemId)
+        const modType = getModuleCapabilityType(mod.itemId)
+        const amp = getSlotAmp(layout, mod.slotIndex)
+        const decodedStats = decodeCraftedItemStats(mod.itemId, mod.stats)
+        installedModuleMass += item.mass
+
+        if (modType === MODULE_ENGINE) {
+            hasEngine = true
+            const caps = computeEngineCapabilities(decodedStats)
+            totalThrust += applySlotMultiplier(caps.thrust, amp)
+            totalEngineDrain += caps.drain
+        } else if (modType === MODULE_GENERATOR) {
+            hasGenerator = true
+            const caps = computeGeneratorCapabilities(decodedStats)
+            totalGenCapacity += applySlotMultiplier(caps.capacity, amp)
+            totalGenRecharge += applySlotMultiplier(caps.recharge, amp)
+        } else if (modType === MODULE_GATHERER) {
+            hasGatherer = true
+            const tier = item.tier
+            const caps = computeGathererCapabilities(decodedStats, tier)
+            totalGathYield += applySlotMultiplier(caps.yield, amp)
+            totalGathDrain += caps.drain
+            if (caps.depth > maxGathDepth) maxGathDepth = caps.depth
+        } else if (modType === MODULE_LOADER) {
+            hasLoader = true
+            const caps = computeLoaderCapabilities(decodedStats)
+            totalLoaderMass += caps.mass
+            totalLoaderThrust += applySlotMultiplier(caps.thrust, amp)
+            totalLoaderQuantity += caps.quantity
+        } else if (modType === MODULE_STORAGE) {
+            const caps = computeStorageCapabilities(decodedStats, baseCapacity)
+            totalStorageBonus += caps.capacityBonus
+        } else if (modType === MODULE_CRAFTER) {
+            hasCrafter = true
+            const caps = computeCrafterCapabilities(decodedStats)
+            totalCrafterSpeed += applySlotMultiplier(caps.speed, amp)
+            totalCrafterDrain += caps.drain
+        } else if (modType === MODULE_HAULER) {
+            hasHauler = true
+            const caps = computeHaulerCapabilities(decodedStats)
+            const eff = applySlotMultiplier(caps.efficiency, amp)
+            totalHaulerCapacity += caps.capacity
+            weightedHaulerEffNum += BigInt(eff) * BigInt(caps.capacity)
+            totalHaulerDrain += caps.drain
+        } else if (modType === MODULE_WARP) {
+            hasWarp = true
+            const caps = computeWarpCapabilities(decodedStats)
+            totalWarpRange += applySlotMultiplier(caps.range, amp)
+        } else if (modType === MODULE_BATTERY) {
+            batteryCount++
+            const vol = decodedStats.volatility ?? 0
+            const thm = decodedStats.thermal ?? 0
+            const pla = decodedStats.plasticity ?? 0
+            const ins = decodedStats.insulation ?? 0
+            totalBatteryStatSum += vol + thm + pla + ins
+        }
+    }
+
+    if (hasGenerator && batteryCount > 0) {
+        const genCapBase = totalGenCapacity
+        const bonusPctNum = 10 * batteryCount + Math.floor((totalBatteryStatSum * 10) / 2997)
+        totalGenCapacity += Math.floor((genCapBase * bonusPctNum) / 100)
+    }
+
+    const result: ComputedCapabilities = {
+        hullmass: computeBaseHullmass(stats) + installedModuleMass,
+        capacity: baseCapacity + totalStorageBonus,
+    }
+
+    if (hasEngine) {
+        result.engines = {thrust: totalThrust, drain: totalEngineDrain}
+    }
+    if (hasGenerator) {
+        result.generator = {
+            capacity: clampUint16(totalGenCapacity),
+            recharge: clampUint16(totalGenRecharge),
+        }
+    }
+    if (hasGatherer) {
+        result.gatherer = {
+            yield: clampUint16(totalGathYield),
+            drain: totalGathDrain,
+            depth: maxGathDepth,
+        }
+    }
+    if (hasLoader) {
+        result.loaders = {
+            mass: totalLoaderMass,
+            thrust: clampUint16(totalLoaderThrust),
+            quantity: totalLoaderQuantity,
+        }
+    }
+    if (hasCrafter) {
+        result.crafter = {speed: clampUint16(totalCrafterSpeed), drain: totalCrafterDrain}
+    }
+    if (hasHauler) {
+        const efficiency =
+            totalHaulerCapacity > 0 ? Number(weightedHaulerEffNum / BigInt(totalHaulerCapacity)) : 0
+        result.hauler = {
+            capacity: totalHaulerCapacity,
+            efficiency: clampUint16(efficiency),
+            drain: totalHaulerDrain,
+        }
+    }
+    if (hasWarp) {
+        result.warp = {range: totalWarpRange}
+    }
+
+    return result
+}
+
+export function computeContainerCapabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const statSum = stats.strength + stats.hardness + stats.saturation
+    const exponent = statSum / 2997.0
+    return {
+        hullmass: computeBaseHullmass(stats),
+        capacity: Math.floor(22000000 * 6 ** exponent),
+    }
+}
+
+export function computeContainerT2Capabilities(stats: Record<string, number>): {
+    hullmass: number
+    capacity: number
+} {
+    const strength = stats.strength
+    const density = stats.density
+    const hardness = stats.hardness
+    const saturation = stats.saturation
+
+    const hullmass = 70000 - 50 * density
+
+    const statSum = strength + hardness + saturation
+    const exponent = statSum / 2947
+    const capacity = Math.floor(24000000 * 6 ** exponent)
+
+    return {hullmass, capacity}
+}

package/src/derivation/capability-mappings.ts

@@ -0,0 +1,117 @@
+import {SLOT_FORMULAS, type SlotConsumerKind} from '../data/capability-formulas'
+import {getStatDefinitions, type StatDefinition} from './stats'
+import {getRecipe, type Recipe} from '../data/recipes-runtime'
+import {getItem} from '../data/catalog'
+import {
+    ITEM_ENGINE_T1,
+    ITEM_EXTRACTOR_T1_PACKED,
+    ITEM_GENERATOR_T1,
+    ITEM_GATHERER_T1,
+    ITEM_LOADER_T1,
+    ITEM_CRAFTER_T1,
+    ITEM_STORAGE_T1,
+    ITEM_HAULER_T1,
+    ITEM_WARP_T1,
+    ITEM_BATTERY_T1,
+    ITEM_SHIP_T1_PACKED,
+    ITEM_CONTAINER_T1_PACKED,
+    ITEM_WAREHOUSE_T1_PACKED,
+    ITEM_CONTAINER_T2_PACKED,
+} from '../data/item-ids'
+import type {StatMapping} from '../data/capabilities'
+
+export const KIND_TO_ITEM_ID: Record<SlotConsumerKind, number> = {
+    engine: ITEM_ENGINE_T1,
+    generator: ITEM_GENERATOR_T1,
+    gatherer: ITEM_GATHERER_T1,
+    loader: ITEM_LOADER_T1,
+    crafter: ITEM_CRAFTER_T1,
+    storage: ITEM_STORAGE_T1,
+    hauler: ITEM_HAULER_T1,
+    warp: ITEM_WARP_T1,
+    battery: ITEM_BATTERY_T1,
+    'ship-t1': ITEM_SHIP_T1_PACKED,
+    'container-t1': ITEM_CONTAINER_T1_PACKED,
+    'warehouse-t1': ITEM_WAREHOUSE_T1_PACKED,
+    'extractor-t1': ITEM_EXTRACTOR_T1_PACKED,
+    'container-t2': ITEM_CONTAINER_T2_PACKED,
+}
+
+/**
+ * Walk a recipe's slot source down to the raw category stat that ultimately
+ * lands in that slot. Returns the StatDefinition or undefined if the trace
+ * dead-ends (unknown sub-component, missing slot, etc.).
+ *
+ * Multi-source sub-slots collapse to `sources[0]`; top-level multi-source slots
+ * are expanded by the caller (`deriveStatMappings`).
+ */
+function traceToRawCategoryStat(
+    recipe: Recipe,
+    source: {inputIndex: number; statIndex: number},
+    visited: Set<number> = new Set()
+): StatDefinition | undefined {
+    const input = recipe.inputs[source.inputIndex]
+    if (!input) return undefined
+    const inputItem = getItem(input.itemId)
+    if (inputItem.type === 'resource' && inputItem.category) {
+        const defs = getStatDefinitions(inputItem.category)
+        return defs[source.statIndex]
+    }
+    if (visited.has(input.itemId)) return undefined
+    const subRecipe = getRecipe(input.itemId)
+    if (!subRecipe) return undefined
+    const subSlot = subRecipe.statSlots[source.statIndex]
+    if (!subSlot) return undefined
+    const subSource = subSlot.sources[0]
+    if (!subSource) return undefined
+    const nextVisited = new Set(visited)
+    nextVisited.add(input.itemId)
+    return traceToRawCategoryStat(subRecipe, subSource, nextVisited)
+}
+
+let cached: StatMapping[] | undefined
+
+export function deriveStatMappings(): StatMapping[] {
+    if (cached) return cached
+    const out: StatMapping[] = []
+    const seen = new Set<string>()
+    for (const [kind, slots] of Object.entries(SLOT_FORMULAS) as [
+        SlotConsumerKind,
+        Record<number, {capability: string; attribute: string}>,
+    ][]) {
+        const itemId = KIND_TO_ITEM_ID[kind]
+        const recipe = getRecipe(itemId)
+        if (!recipe) continue
+        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)
+                if (!stat) continue
+                const key = `${stat.label}|${consumer.capability}|${consumer.attribute}`
+                if (seen.has(key)) continue
+                seen.add(key)
+                out.push({
+                    stat: stat.label,
+                    capability: consumer.capability,
+                    attribute: consumer.attribute,
+                })
+            }
+        }
+    }
+    cached = out
+    return out
+}
+
+export function getStatMappings(): StatMapping[] {
+    return deriveStatMappings()
+}
+
+export function getStatMappingsForStat(stat: string): StatMapping[] {
+    return deriveStatMappings().filter((m) => m.stat === stat)
+}
+
+export function getStatMappingsForCapability(capability: string): StatMapping[] {
+    return deriveStatMappings().filter((m) => m.capability === capability)
+}

package/src/derivation/crafting.ts

@@ -1,6 +1,6 @@
 import {UInt64} from '@wharfkit/antelope'
 import type {ResourceCategory} from '../types'
-import {findItemByCategoryAndTier, getRecipe, type Recipe} from '../data/recipes-runtime'
+import {getRecipe, type Recipe} from '../data/recipes-runtime'
 import {getItem} from '../data/catalog'
 import {getStatDefinitions} from './stats'
 import {deriveResourceStats} from './stratum'
@@ -58,11 +58,8 @@ function keyForStatSlot(
 function keyForRecipeInputStat(recipe: Recipe, inputIndex: number, statIndex: number): string {
     const input = recipe.inputs[inputIndex]
     if (!input) return ''
-    if ('category' in input) {
-        const defs = getStatDefinitions(input.category)
-        return defs[statIndex]?.key ?? ''
-    }
-    // itemId-typed input — its stats follow that item's own statSlots layout.
+    // Every input names an item by id; its stats follow that item's own layout
+    // (resource stat definitions for resources, statSlots for crafted items).
     const innerKeys = getItemStatKeys(input.itemId)
     return innerKeys[statIndex] ?? ''
 }
@@ -117,10 +114,11 @@ export function computeComponentStats(
         const src = slot.sources[0]
         const key = keyForStatSlot(recipe, slot)
         const input = src ? recipe.inputs[src.inputIndex] : undefined
-        if (!input || !('category' in input)) {
+        const inputItem = input ? getItem(input.itemId) : undefined
+        if (!inputItem || inputItem.type !== 'resource' || !inputItem.category) {
             return {key, value: Math.max(1, Math.min(999, 0))}
         }
-        const matching = categoryStacks.find((cs) => cs.category === input.category)
+        const matching = categoryStacks.find((cs) => cs.category === inputItem.category)
         const value = matching ? blendStacks(matching.stacks, key) : 0
         return {key, value: Math.max(1, Math.min(999, value))}
     })
@@ -147,7 +145,7 @@ export function computeEntityStats(
         const key = keyForStatSlot(recipe, slot)
         if (!src) return {key, value: 1}
         const input = recipe.inputs[src.inputIndex]
-        if (!input || 'category' in input) {
+        if (!input) {
             return {key, value: 1}
         }
         const blended = blendedByComponent[input.itemId] ?? {}
@@ -185,12 +183,7 @@ export function computeInputMass(itemId: number): number {
 
     let total = 0
     for (const input of recipe.inputs) {
-        if ('itemId' in input) {
-            total += getItem(input.itemId).mass * input.quantity
-        } else {
-            const item = findItemByCategoryAndTier(input.category, input.tier)
-            total += item.mass * input.quantity
-        }
+        total += getItem(input.itemId).mass * input.quantity
     }
     return total
 }
@@ -305,10 +298,13 @@ export function computeCraftedOutputStats(
             const key = keyForRecipeInputStat(recipe, src.inputIndex, src.statIndex)
             const input = recipe.inputs[src.inputIndex]
             let value = 0
-            if (input && 'category' in input) {
-                value = blendStacks(decodedByCategory[input.category] ?? [], key)
-            } else if (input) {
-                value = blendedByItem[input.itemId]?.[key] ?? 0
+            if (input) {
+                const inputItem = getItem(input.itemId)
+                if (inputItem.type === 'resource' && inputItem.category) {
+                    value = blendStacks(decodedByCategory[inputItem.category] ?? [], key)
+                } else {
+                    value = blendedByItem[input.itemId]?.[key] ?? 0
+                }
             }
             out.push(Math.max(1, Math.min(999, value)))
         } else {
@@ -319,10 +315,13 @@ export function computeCraftedOutputStats(
                 const input = recipe.inputs[src.inputIndex]
                 const weight = recipe.blendWeights[src.inputIndex] ?? 1
                 let value = 0
-                if (input && 'category' in input) {
-                    value = blendStacks(decodedByCategory[input.category] ?? [], key)
-                } else if (input) {
-                    value = blendedByItem[input.itemId]?.[key] ?? 0
+                if (input) {
+                    const inputItem = getItem(input.itemId)
+                    if (inputItem.type === 'resource' && inputItem.category) {
+                        value = blendStacks(decodedByCategory[inputItem.category] ?? [], key)
+                    } else {
+                        value = blendedByItem[input.itemId]?.[key] ?? 0
+                    }
                 }
                 weightedSum += value * weight
                 totalWeight += weight
@@ -340,7 +339,7 @@ export function computeCraftedOutputStats(
  * returns a UInt64 whose bit-packed form matches what the contract writes
  * to cargo_item.stats on gather.
  *
- * Use this whenever off-chain code simulates a gather (testmap, player
+ * Use this whenever off-chain code simulates a gather (webapp, player
  * scanners that project cargo outcomes) and needs a value that matches
  * what on-chain cargo would carry.
  */

package/src/derivation/index.ts

@@ -7,6 +7,7 @@ export {
     getEligibleResources,
     getResourceWeight,
     getLocationCandidates,
+    getLocationProfile,
     getDepthThreshold,
     getResourceTier,
     DEPTH_THRESHOLD_T1,
@@ -16,7 +17,9 @@ export {
     DEPTH_THRESHOLD_T5,
     LOCATION_MIN_DEPTH,
     LOCATION_MAX_DEPTH,
-    YIELD_THRESHOLD,
+    yieldThresholdAt,
+    YIELD_FRACTION_SHALLOW,
+    YIELD_FRACTION_DEEP,
     PLANET_SUBTYPE_GAS_GIANT,
     PLANET_SUBTYPE_ROCKY,
     PLANET_SUBTYPE_TERRESTRIAL,
@@ -25,8 +28,11 @@ export {
     PLANET_SUBTYPE_INDUSTRIAL,
 } from './resources'
 
-export {RESERVE_TIERS, TIER_ROLL_MAX, rollTier, rollWithinTier} from './tiers'
+export {RESERVE_TIERS, TIER_ROLL_MAX, tierOfReserve, rollTier, rollWithinTier} from './tiers'
 export type {ReserveTier, TierRange} from './tiers'
 
+export {getEffectiveReserve} from './reserve-regen'
+export type {EffectiveReserveInput} from './reserve-regen'
+
 export * from './stats'
 export * from './crafting'

package/src/derivation/reserve-regen.ts

@@ -0,0 +1,34 @@
+import type {BlockTimestamp, UInt32} from '@wharfkit/antelope'
+
+export interface EffectiveReserveInput {
+    remaining: UInt32 | number
+    max_reserve: UInt32 | number
+    last_block: BlockTimestamp
+}
+
+function toNumber(value: UInt32 | number): number {
+    return typeof value === 'number' ? value : Number(value)
+}
+
+function slotsBetween(now: BlockTimestamp, last: BlockTimestamp): number {
+    const nowMs = now.toMilliseconds()
+    const lastMs = last.toMilliseconds()
+    if (nowMs <= lastMs) return 0
+    return Math.floor((nowMs - lastMs) / 500)
+}
+
+export function getEffectiveReserve(
+    row: EffectiveReserveInput,
+    now: BlockTimestamp,
+    epochSeconds: number
+): number {
+    const remaining = toNumber(row.remaining)
+    const max = toNumber(row.max_reserve)
+    if (remaining >= max) return max
+    const epochSlots = epochSeconds * 2
+    if (epochSlots === 0) return remaining
+    const elapsed = slotsBetween(now, row.last_block)
+    const regen = Math.floor((max * elapsed) / epochSlots)
+    const effective = remaining + regen
+    return effective >= max ? max : effective
+}