mining

Interfaces

FleetMiningOutput

Defined in: packages/sage/src/mining/index.ts:108

One selected and registry-resolved output of an active mining Fleet.

Example

declare const output: FleetMiningOutput;
console.log(output.cargo.name, output.unitsPerSecond);

Extends

ResourceDepositItem

Properties

activeMinerCountRaw

readonly activeMinerCountRaw: bigint;

Defined in: packages/sage/src/mining/index.ts:56

Inherited from

ResourceDepositItem.activeMinerCountRaw

amountMinedUnitsRaw

readonly amountMinedUnitsRaw: bigint;

Defined in: packages/sage/src/mining/index.ts:55

Inherited from

ResourceDepositItem.amountMinedUnitsRaw

cargo

readonly cargo: CargoDefinitionSummary;

Defined in: packages/sage/src/mining/index.ts:53

Inherited from

ResourceDepositItem.cargo

richness

readonly richness: WorldFixedValue;

Defined in: packages/sage/src/mining/index.ts:54

Inherited from

ResourceDepositItem.richness

unitsPerSecond

readonly unitsPerSecond: number;

Defined in: packages/sage/src/mining/index.ts:110

Nominal cargo units per second, with Fleet capacity shared among selected resources.

FleetMiningSnapshot

Defined in: packages/sage/src/mining/index.ts:120

Immutable current extraction relationship for one active mining Fleet.

Example

declare const mining: FleetMiningSnapshot;
console.log(mining.outputs);

Properties

asteroid

readonly asteroid: EntityRef<"celestialBody">;

Defined in: packages/sage/src/mining/index.ts:124

fleet

readonly fleet: EntityRef<"fleet">;

Defined in: packages/sage/src/mining/index.ts:122

kind

readonly kind: "fleetMining";

Defined in: packages/sage/src/mining/index.ts:121

lastUpdatedAtUnixSeconds

readonly lastUpdatedAtUnixSeconds: bigint;

Defined in: packages/sage/src/mining/index.ts:125

miningRate

readonly miningRate: {
  raw: bigint;
  unitsPerSecond: number;
};

Defined in: packages/sage/src/mining/index.ts:128

Fleet base rate before sharing among selected resources and applying richness.

raw

readonly raw: bigint;

unitsPerSecond

readonly unitsPerSecond: number;

outputs

readonly outputs: readonly FleetMiningOutput[];

Defined in: packages/sage/src/mining/index.ts:132

ownerProfile

readonly ownerProfile: EntityRef<"profile">;

Defined in: packages/sage/src/mining/index.ts:123

regionXpModifier

readonly regionXpModifier: WorldFixedValue;

Defined in: packages/sage/src/mining/index.ts:126

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/mining/index.ts:133

Returns

unknown

MiningEstimate

Defined in: packages/sage/src/mining/estimate.ts:75

Immutable, JSON-safe constant-rate estimate, not a settlement guarantee. Projected quantities are fractional numbers; chain rounding, changing state, eligibility and tick ordering are excluded. A null limit means unbounded by that constraint, never an unknown balance. No-output scenarios run for zero time and project no upkeep. An initially full hold conservatively permits no mining, even when Food outflow could offset output: tick ordering is not established.

Example

declare const estimate: MiningEstimate;
console.log(estimate.durationSeconds, estimate.limitingFactors);

Properties

basis

readonly basis: "official-model-estimate";

Defined in: packages/sage/src/mining/estimate.ts:76

consumedAmmoUnits

readonly consumedAmmoUnits: number;

Defined in: packages/sage/src/mining/estimate.ts:95

consumedFoodUnits

readonly consumedFoodUnits: number;

Defined in: packages/sage/src/mining/estimate.ts:94

durationSeconds

readonly durationSeconds: number;

Defined in: packages/sage/src/mining/estimate.ts:78

Requested duration clipped to the modeled limits, in seconds.

finalOccupiedSpace

readonly finalOccupiedSpace: number;

Defined in: packages/sage/src/mining/estimate.ts:96

foodVolumeOutflowPerSecond

readonly foodVolumeOutflowPerSecond: number;

Defined in: packages/sage/src/mining/estimate.ts:85

limitingFactors

readonly limitingFactors: readonly MiningEstimateLimit[];

Defined in: packages/sage/src/mining/estimate.ts:93

limitsSeconds

readonly limitsSeconds: {
  ammo: number | null;
  cargo: number | null;
  food: number | null;
};

Defined in: packages/sage/src/mining/estimate.ts:88

ammo

readonly ammo: number | null;

cargo

readonly cargo: number | null;

food

readonly food: number | null;

netCargoGrowthPerSecond

readonly netCargoGrowthPerSecond: number;

Defined in: packages/sage/src/mining/estimate.ts:87

May be negative when Food consumption frees more space than mining uses.

outputs

readonly outputs: readonly {
  cargoId: number;
  projectedUnits: number;
  unitsPerSecond: number;
}[];

Defined in: packages/sage/src/mining/estimate.ts:79

resourceVolumeInflowPerSecond

readonly resourceVolumeInflowPerSecond: number;

Defined in: packages/sage/src/mining/estimate.ts:84

MiningEstimateInput

Defined in: packages/sage/src/mining/estimate.ts:37

Explicit constant-rate Asteroid scenario. Balances and rates use cargo units; capacity, occupancy and storage costs use translated storage units. Occupancy includes all available Food; Ammo is held separately and frees no cargo space. Supply all 1–8 selected resources, including zero-yield rows. Fleet rate already includes ship/component effects: do not apply those again in the multipliers.

Example

const input: MiningEstimateInput = {
  fleetUnitsPerSecond: 2, durationSeconds: 60,
  resources: [{ cargoId: 300, richness: 1, storageCost: 1, runtimeMultiplier: 1 }],
  cargo: { occupiedSpace: 10, capacity: 100 },
  food: { availableUnits: 10, burnUnitsPerSecond: 0.1, storageCost: 1 },
  ammo: { availableUnits: 10, burnUnitsPerSecond: 0.1 },
};

Properties

ammo

readonly ammo: {
  availableUnits: number;
  burnUnitsPerSecond: number;
};

Defined in: packages/sage/src/mining/estimate.ts:48

availableUnits

readonly availableUnits: number;

burnUnitsPerSecond

readonly burnUnitsPerSecond: number;

cargo

readonly cargo: {
  capacity: number;
  occupiedSpace: number;
};

Defined in: packages/sage/src/mining/estimate.ts:42

capacity

readonly capacity: number;

occupiedSpace

readonly occupiedSpace: number;

durationSeconds

readonly durationSeconds: number;

Defined in: packages/sage/src/mining/estimate.ts:40

Requested duration; the result reports the clipped duration.

fleetUnitsPerSecond

readonly fleetUnitsPerSecond: number;

Defined in: packages/sage/src/mining/estimate.ts:38

food

readonly food: {
  availableUnits: number;
  burnUnitsPerSecond: number;
  storageCost: number;
};

Defined in: packages/sage/src/mining/estimate.ts:43

availableUnits

readonly availableUnits: number;

burnUnitsPerSecond

readonly burnUnitsPerSecond: number;

storageCost

readonly storageCost: number;

resources

readonly resources: readonly MiningEstimateResourceInput[];

Defined in: packages/sage/src/mining/estimate.ts:41

MiningEstimateResourceInput

Defined in: packages/sage/src/mining/estimate.ts:14

One selected Asteroid resource, using translated storage units rather than encoded fixed point. runtimeMultiplier is the caller’s effective multiplier, including any applicable crew/research effects. No modifier composition or eligibility is inferred.

Example

const resource: MiningEstimateResourceInput = {
  cargoId: 300, richness: 2, storageCost: 2, runtimeMultiplier: 1.5,
};

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/mining/estimate.ts:15

richness

readonly richness: number;

Defined in: packages/sage/src/mining/estimate.ts:16

runtimeMultiplier

readonly runtimeMultiplier: number;

Defined in: packages/sage/src/mining/estimate.ts:18

storageCost

readonly storageCost: number;

Defined in: packages/sage/src/mining/estimate.ts:17

MiningOutputRate

Defined in: packages/sage/src/mining/index.ts:96

One nominal resource output after sharing Fleet capacity and applying richness.

Example

const rate: MiningOutputRate = { cargoId: 8, unitsPerSecond: 4.5 };

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/mining/index.ts:97

unitsPerSecond

readonly unitsPerSecond: number;

Defined in: packages/sage/src/mining/index.ts:98

MiningOutputRateInput

Defined in: packages/sage/src/mining/index.ts:85

A pure rate input pairing one cargo id with Asteroid richness.

Example

const input: MiningOutputRateInput = { cargoId: 8, richness: 1.5 };

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/mining/index.ts:86

richness

readonly richness: number;

Defined in: packages/sage/src/mining/index.ts:87

MiningProfile

Defined in: packages/sage/src/mining/profile.ts:44

Reference mining values for one selected resource at the given richness, with no crew, research or rare-mineral multiplier. fullHold starts from an empty hold carrying exactly the Food it burns and a full Ammo bank; it is null when nothing is mined, the hold has no capacity, or Food outflow would keep pace with output. Ratios are null when that consumable is not burned.

Example

declare const profile: MiningProfile;
console.log(profile.unitsPerHour, profile.fullHold?.durationSeconds);

Properties

basis

readonly basis: "official-model-estimate";

Defined in: packages/sage/src/mining/profile.ts:45

fullHold

readonly fullHold:
  | {
  ammoUnits: number;
  durationSeconds: number;
  foodUnits: number;
  limitedBy: "cargo" | "ammo";
  minedUnits: number;
}
  | null;

Defined in: packages/sage/src/mining/profile.ts:52

Union Members

Type Literal

{
  ammoUnits: number;
  durationSeconds: number;
  foodUnits: number;
  limitedBy: "cargo" | "ammo";
  minedUnits: number;
}

ammoUnits

readonly ammoUnits: number;

durationSeconds

readonly durationSeconds: number;

foodUnits

readonly foodUnits: number;

Food burned, which is also the Food to carry in the hold at the start.

limitedBy

readonly limitedBy: "cargo" | "ammo";

minedUnits

readonly minedUnits: number;

null

unitsPerAmmo

readonly unitsPerAmmo: number | null;

Defined in: packages/sage/src/mining/profile.ts:51

Resource units mined per Ammo burned.

unitsPerFood

readonly unitsPerFood: number | null;

Defined in: packages/sage/src/mining/profile.ts:49

Resource units mined per Food burned.

unitsPerHour

readonly unitsPerHour: number;

Defined in: packages/sage/src/mining/profile.ts:47

unitsPerSecond

readonly unitsPerSecond: number;

Defined in: packages/sage/src/mining/profile.ts:46

MiningProfileInput

Defined in: packages/sage/src/mining/profile.ts:17

Fleet or ship configuration cargo stats plus one reference Asteroid resource. Richness and storage costs are explicit assumptions: storage costs are translated storage units per unit (an encoded 256 is 1), not raw values.

Example

declare const ship: { readonly stats: MiningProfileInput['stats'] };
const input: MiningProfileInput = {
  stats: ship.stats, richness: 1, resourceStorageCost: 1, foodStorageCost: 1,
};

Properties

foodStorageCost

readonly foodStorageCost: number;

Defined in: packages/sage/src/mining/profile.ts:30

resourceStorageCost

readonly resourceStorageCost: number;

Defined in: packages/sage/src/mining/profile.ts:29

richness

readonly richness: number;

Defined in: packages/sage/src/mining/profile.ts:28

stats

readonly stats: {
  cargo: Pick<FleetCargoStatsData,
     | "miningRate"
     | "foodConsumptionRate"
     | "ammoConsumptionRate"
     | "cargoCapacity"
    | "ammoCapacity">;
};

Defined in: packages/sage/src/mining/profile.ts:18

cargo

readonly cargo: Pick<FleetCargoStatsData,
  | "miningRate"
  | "foodConsumptionRate"
  | "ammoConsumptionRate"
  | "cargoCapacity"
| "ammoCapacity">;

ResourceDepositItem

Defined in: packages/sage/src/mining/index.ts:52

One registry-resolved resource row nested in an Asteroid deposit.

Example

declare const resource: ResourceDepositItem;
console.log(resource.cargo.name, resource.richness.value);

Extended by

FleetMiningOutput

Properties

activeMinerCountRaw

readonly activeMinerCountRaw: bigint;

Defined in: packages/sage/src/mining/index.ts:56

amountMinedUnitsRaw

readonly amountMinedUnitsRaw: bigint;

Defined in: packages/sage/src/mining/index.ts:55

cargo

readonly cargo: CargoDefinitionSummary;

Defined in: packages/sage/src/mining/index.ts:53

richness

readonly richness: WorldFixedValue;

Defined in: packages/sage/src/mining/index.ts:54

ResourceDepositSnapshot

Defined in: packages/sage/src/mining/index.ts:66

Immutable, translated Asteroid resource-deposit snapshot.

Example

declare const deposit: ResourceDepositSnapshot;
console.log(deposit.resources);

Properties

address

readonly address: Address;

Defined in: packages/sage/src/mining/index.ts:68

bodyId

readonly bodyId: number;

Defined in: packages/sage/src/mining/index.ts:69

game

readonly game: Address;

Defined in: packages/sage/src/mining/index.ts:71

kind

readonly kind: "resourceDeposit";

Defined in: packages/sage/src/mining/index.ts:67

lastSyncedAtUnixSeconds

readonly lastSyncedAtUnixSeconds: bigint;

Defined in: packages/sage/src/mining/index.ts:74

name

readonly name: string;

Defined in: packages/sage/src/mining/index.ts:70

resources

readonly resources: readonly ResourceDepositItem[];

Defined in: packages/sage/src/mining/index.ts:75

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/mining/index.ts:72

systemSequenceId

readonly systemSequenceId: bigint;

Defined in: packages/sage/src/mining/index.ts:73

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/mining/index.ts:76

Returns

unknown

Type Aliases

MiningDiscoveryOptions

type MiningDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy">;

Defined in: packages/sage/src/mining/index.ts:142

Options supported by owner-scoped active-mining discovery.

Example

const options: MiningDiscoveryOptions = { commitment: 'confirmed' };

MiningEstimateLimit

type MiningEstimateLimit = "duration" | "food" | "ammo" | "cargo" | "no-output";

Defined in: packages/sage/src/mining/estimate.ts:60

Constraints reached at the end of an estimate; simultaneous limits are retained.

Example

const reason: MiningEstimateLimit = 'food';

Functions

deriveMiningEstimate()

function deriveMiningEstimate(input): MiningEstimate;

Defined in: packages/sage/src/mining/estimate.ts:133

Estimates constant-rate Asteroid output, clipping duration to Food, Ammo and cargo capacity. Each rate is Fleet rate / selected count × richness × explicit effective runtime multiplier. Food consumption offsets volume growth while mining; Ammo does not. Hardness is absent from the official current C4 model. This is pure: it neither reads accounts nor validates resource eligibility.

Parameters

Parameter	Type
`input`	`MiningEstimateInput`

Returns

MiningEstimate

Throws

InvalidDerivationInputError for invalid selections, inconsistent cargo occupancy, negative/nonfinite values or arithmetic overflow.

Example

const estimate = deriveMiningEstimate({
  fleetUnitsPerSecond: 2, durationSeconds: 60,
  resources: [{ cargoId: 300, richness: 1, storageCost: 1, runtimeMultiplier: 1 }],
  cargo: { occupiedSpace: 10, capacity: 100 },
  food: { availableUnits: 10, burnUnitsPerSecond: 0.1, storageCost: 1 },
  ammo: { availableUnits: 10, burnUnitsPerSecond: 0.1 },
});
console.log(estimate.outputs, estimate.limitingFactors);

deriveMiningOutputRates()

function deriveMiningOutputRates(fleetUnitsPerSecond, outputs): readonly MiningOutputRate[];

Defined in: packages/sage/src/mining/index.ts:312

Shares Fleet units/second equally among selected resources, then applies richness. Supply the complete selected resource list, including zero-richness selections. An empty selection returns no rates. Results are nominal estimates; cargo limits, upkeep and whole-unit settlement remain chain-authoritative.

Parameters

Parameter	Type
`fleetUnitsPerSecond`	`number`
`outputs`	readonly `MiningOutputRateInput`[]

Returns

readonly MiningOutputRate[]

Example

const rates = deriveMiningOutputRates(2, [{ cargoId: 8, richness: 1.5 }]);

deriveMiningProfile()

function deriveMiningProfile(input): MiningProfile;

Defined in: packages/sage/src/mining/profile.ts:107

Derives reference mining values from Fleet or ship configuration stats with the official constant-rate model behind deriveMiningEstimate. The Fleet rate times richness gives output; foodConsumptionRate and ammoConsumptionRate are burned per second while mining, as the official SAGE Editor Suite scenario applies them.

The full-hold scenario carries Food equal to rate × fill time, so the Food burned frees exactly the space it occupied and the hold fills in capacity ÷ (output × storage cost) seconds, unless the Ammo bank runs out first. This is an estimate, not a settlement: fixed-point rounding, eligibility, regional research, planet-exit Fuel and changing state are excluded.

Parameters

Parameter	Type
`input`	`MiningProfileInput`

Returns

MiningProfile

Throws

InvalidDerivationInputError for negative or non-finite stats or assumptions, or derived values that overflow to Infinity.

Example

const profile = deriveMiningProfile({
  stats: {
    cargo: {
      miningRate: { raw: 16384n, value: 1 },
      foodConsumptionRate: { raw: 2048n, value: 0.125 },
      ammoConsumptionRate: { raw: 1024n, value: 0.0625 },
      cargoCapacity: 100n,
      ammoCapacity: 1000n,
    },
  },
  richness: 2, resourceStorageCost: 1, foodStorageCost: 1,
});
console.log(profile.unitsPerHour); // 7200
console.log(profile.fullHold?.durationSeconds); // 50: 100 capacity / 2 per second
console.log(profile.fullHold?.foodUnits); // 6.25 Food carried and burned

deriveMiningStateAgeSeconds()

function deriveMiningStateAgeSeconds(lastUpdatedAtUnixSeconds, atUnixSeconds): number;

Defined in: packages/sage/src/mining/index.ts:292

Derives mining-state age in whole seconds and clamps future timestamps.

Parameters

Parameter	Type
`lastUpdatedAtUnixSeconds`	`bigint`
`atUnixSeconds`	`bigint`

Returns

number

Example

const age = deriveMiningStateAgeSeconds(100n, 112n); // 12

getFleetMiningState()

function getFleetMiningState(
   context,
   fleet,
   options?): Promise<
  | FleetMiningSnapshot
| undefined>;

Defined in: packages/sage/src/mining/index.ts:476

Reads a Fleet and returns its active extraction relationship, if mining.

Parameters

Parameter	Type
`context`	`SageContext`
`fleet`	`Address`
`options?`	`ReadOptions`

Returns

Promise< | FleetMiningSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const fleet: Address;
const mining = await getFleetMiningState(ctx, fleet);

getFleetMiningStatesByOwner()

function getFleetMiningStatesByOwner(
   context,
   owner,
options?): Promise<readonly FleetMiningSnapshot[]>;

Defined in: packages/sage/src/mining/index.ts:500

Finds active mining Fleets for one owner through stable Fleet filters.

Parameters

Parameter	Type
`context`	`SageContext`
`owner`	`Address`
`options?`	`MiningDiscoveryOptions`

Returns

Promise<readonly FleetMiningSnapshot[]>

Example

declare const ctx: SageContext;
declare const owner: Address;
const mining = await getFleetMiningStatesByOwner(ctx, owner);

getResourceDeposit()

function getResourceDeposit(
   context,
   asteroid,
options?): Promise<ResourceDepositSnapshot>;

Defined in: packages/sage/src/mining/index.ts:245

Reads a required Asteroid resource deposit by CelestialBody address.

Parameters

Parameter	Type
`context`	`SageContext`
`asteroid`	`Address`
`options?`	`ReadOptions`

Returns

Promise<ResourceDepositSnapshot>

Example

declare const ctx: SageContext;
declare const asteroid: Address;
const deposit = await getResourceDeposit(ctx, asteroid);

maybeGetResourceDeposit()

function maybeGetResourceDeposit(
   context,
   asteroid,
   options?): Promise<
  | ResourceDepositSnapshot
| undefined>;

Defined in: packages/sage/src/mining/index.ts:270

Reads an optional Asteroid resource deposit by CelestialBody address.

Returns undefined only when the account does not exist. A present non-Asteroid CelestialBody throws AccountDecodeError because it is not a resource deposit.

Parameters

Parameter	Type
`context`	`SageContext`
`asteroid`	`Address`
`options?`	`ReadOptions`

Returns

Promise< | ResourceDepositSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const asteroid: Address;
const deposit = await maybeGetResourceDeposit(ctx, asteroid);

projectMiningOutputUnits()

function projectMiningOutputUnits(unitsPerSecond, elapsedSeconds): number;

Defined in: packages/sage/src/mining/index.ts:346

Projects nominal output units from a rate and elapsed seconds.

Parameters

Parameter	Type
`unitsPerSecond`	`number`
`elapsedSeconds`	`number`

Returns

number

Example

const units = projectMiningOutputUnits(4.5, 20); // 90