cargo

Interfaces

CargoCapacity

Defined in: packages/sage/src/internal/cargo.ts:58

Exact used, total, remaining, and excess values for one capacity axis.

Example

declare const capacity: CargoCapacity;
console.log(capacity.remainingRaw);

Properties

overCapacityRaw

readonly overCapacityRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:62

remainingRaw

readonly remainingRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:61

totalRaw

readonly totalRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:60

usedRaw

readonly usedRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:59

---

CargoInventoryItem

Defined in: packages/sage/src/internal/cargo.ts:32

Exact cargo quantity joined to its lazily loaded definition.

Example

declare const item: CargoInventoryItem;
console.log(item.name, item.quantityRaw);

Extends

• CargoDefinitionSummary

Properties

categoryId

readonly categoryId: number;

Defined in: packages/sage/src/registry/index.ts:119

Inherited from

CargoDefinitionSummary.categoryId

id

readonly id: number;

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

Inherited from

CargoDefinitionSummary.id

mint

readonly mint: Address;

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

Inherited from

CargoDefinitionSummary.mint

name

readonly name: string;

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

Inherited from

CargoDefinitionSummary.name

quantityRaw

readonly quantityRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:34

Exact on-chain cargo quantity in the cargo type’s raw units.

storageCost

readonly storageCost: number;

Defined in: packages/sage/src/registry/index.ts:127

Encoded storage cost with 8 fractional bits: 256 means one whole storage unit. For a nonnegative bigint quantity, use (quantity * BigInt(storageCost) + 255n) / 256n. Round each transfer row up before summing; Fleet capacities and pod usage are whole units.

Inherited from

CargoDefinitionSummary.storageCost

---

CargoPodInventory

Defined in: packages/sage/src/internal/cargo.ts:44

One nested C4 CargoPod translated into an immutable inventory value.

Example

declare const pod: CargoPodInventory;
console.log(pod.usedStorageUnitsRaw, pod.items);

Properties

items

readonly items: readonly CargoInventoryItem[];

Defined in: packages/sage/src/internal/cargo.ts:48

sequenceId

readonly sequenceId: number;

Defined in: packages/sage/src/internal/cargo.ts:45

usedStorageUnitsRaw

readonly usedStorageUnitsRaw: bigint;

Defined in: packages/sage/src/internal/cargo.ts:47

Exact aggregate storage use reported by the parent account.

---

FleetCargoInventorySnapshot

Defined in: packages/sage/src/cargo/index.ts:78

Immutable cargo inventory projected from the CargoPods nested in a Fleet.

Example

declare const inventory: FleetCargoInventorySnapshot;
console.log(inventory.cargoHold.items);

Extends

• Omit<ResolvedFleetCargoInventory, "ownerProfile">

Extended by

• FleetCargoInventoryView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/cargo/index.ts:84

Parent Fleet address; CargoPods are nested values and have no own address.

ammo

readonly ammo: CargoInventoryItem;

Defined in: packages/sage/src/internal/cargo.ts:78

Inherited from

Omit.ammo

capacities

readonly capacities: {
  ammoUnits: CargoCapacity;
  cargoStorageUnits: CargoCapacity;
  fuelUnits: CargoCapacity;
};

Defined in: packages/sage/src/internal/cargo.ts:79

ammoUnits

readonly ammoUnits: CargoCapacity;

cargoStorageUnits

readonly cargoStorageUnits: CargoCapacity;

fuelUnits

readonly fuelUnits: CargoCapacity;

Inherited from

Omit.capacities

cargoHold

readonly cargoHold: CargoPodInventory;

Defined in: packages/sage/src/internal/cargo.ts:74

Inherited from

Omit.cargoHold

components

readonly components: CargoPodInventory;

Defined in: packages/sage/src/internal/cargo.ts:75

Inherited from

Omit.components

fleet

readonly fleet: EntityRef<"fleet">;

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

fuel

readonly fuel: CargoInventoryItem;

Defined in: packages/sage/src/internal/cargo.ts:77

Inherited from

Omit.fuel

kind

readonly kind: "fleetCargoInventory";

Defined in: packages/sage/src/cargo/index.ts:82

ownerProfile

readonly ownerProfile: EntityRef<"profile">;

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

respawningCargo

readonly respawningCargo: CargoPodInventory;

Defined in: packages/sage/src/internal/cargo.ts:76

Inherited from

Omit.respawningCargo

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

Type Aliases

CargoDefinition

type CargoDefinition = CargoDefinitionSummary;

Defined in: packages/sage/src/cargo/index.ts:50

Stable cargo definition resolved lazily from the configured Game registry.

Example

declare const definition: CargoDefinition;
console.log(definition.name, definition.storageCost);

---

CargoDefinitionLookupOptions

type CargoDefinitionLookupOptions = DefinitionLookupOptions;

Defined in: packages/sage/src/cargo/index.ts:58

Sequence expectation used when resolving a cargo definition.

Example

const options: CargoDefinitionLookupOptions = { expectedSequenceId: 4 };

---

CargoDiscoveryOptions

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

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

Options supported by targeted Fleet cargo inventory discovery.

Example

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

Functions

getCargoDefinition()

function getCargoDefinition(
   context,
   cargoId,
options?): Promise<CargoDefinitionSummary>;

Defined in: packages/sage/src/cargo/index.ts:154

Resolves one cargo definition without loading the Game registry eagerly.

Parameters

Parameter	Type
context	SageContext
cargoId	number
options?	DefinitionLookupOptions

Returns

Promise<CargoDefinitionSummary>

Example

declare const ctx: SageContext;
const fuel = await getCargoDefinition(ctx, 1);

---

getFleetCargoInventoriesByOwner()

function getFleetCargoInventoriesByOwner(
   context,
   profileAddress,
options?): Promise<readonly FleetCargoInventorySnapshot[]>;

Defined in: packages/sage/src/cargo/index.ts:219

Discovers CargoPod inventories for Fleets owned by a Player Profile.

Parameters

Parameter	Type
context	SageContext
profileAddress	Address
options?	CargoDiscoveryOptions

Returns

Promise<readonly FleetCargoInventorySnapshot[]>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const inventories = await getFleetCargoInventoriesByOwner(ctx, profileAddress);

---

getFleetCargoInventory()

function getFleetCargoInventory(
   context,
   fleetAddress,
options?): Promise<FleetCargoInventorySnapshot>;

Defined in: packages/sage/src/cargo/index.ts:170

Reads the required CargoPods nested in a Fleet account.

Parameters

Parameter	Type
context	SageContext
fleetAddress	Address
options?	ReadOptions

Returns

Promise<FleetCargoInventorySnapshot>

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const inventory = await getFleetCargoInventory(ctx, fleetAddress);

---

maybeGetFleetCargoInventory()

function maybeGetFleetCargoInventory(
   context,
   fleetAddress,
   options?): Promise<
  | FleetCargoInventorySnapshot
| undefined>;

Defined in: packages/sage/src/cargo/index.ts:194

Reads optional CargoPods nested in a Fleet account.

Parameters

Parameter	Type
context	SageContext
fleetAddress	Address
options?	ReadOptions

Returns

Promise< | FleetCargoInventorySnapshot | undefined>

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const inventory = await maybeGetFleetCargoInventory(ctx, fleetAddress);

References

listCargoDefinitions

Re-exports listCargoDefinitions