fleets/actions

Interfaces

PlanAddShipToFleetOptions

Defined in: packages/sage/src/fleets/actions/add-ship.ts:24

Explicit address-only selection of escrowed ships for an owned Docked Fleet.

Example

declare const profile: Address, authority: Address;
const options: PlanAddShipToFleetOptions = {authorization:{profile,authority,keyIndex:0},shipId:1,amount:1n};

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/fleets/actions/add-ship.ts:27

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/add-ship.ts:25

shipId

readonly shipId: number;

Defined in: packages/sage/src/fleets/actions/add-ship.ts:26

---

PlanCreateFleetOptions

Defined in: packages/sage/src/fleets/actions/create-fleet.ts:24

Address-only options for creating an empty Fleet at an existing own-faction StarbasePlayer.

Example

declare const profile:Address, authority:Address, system:Address;
const options:PlanCreateFleetOptions={authorization:{profile,authority,keyIndex:0},system,label:'Scout'};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/create-fleet.ts:25

label

readonly label: string;

Defined in: packages/sage/src/fleets/actions/create-fleet.ts:27

system

readonly system: Address;

Defined in: packages/sage/src/fleets/actions/create-fleet.ts:26

---

PlanDepositShipsToGameOptions

Defined in: packages/sage/src/fleets/actions/ship-import.ts:61

Exact whole ships to import under one explicit configuration ID. Optional escrow creation requires an explicit payer; it never registers onboarding accounts.

Example

declare const owner: Address;
declare const authorization: PlanAuthorization;
const options: PlanDepositShipsToGameOptions = { shipId: 1, amount: 2n, owner, authorization };

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:63

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:65

escrowAccount?

readonly optional escrowAccount?: {
  mode: "create-if-missing";
  payer: Address;
};

Defined in: packages/sage/src/fleets/actions/ship-import.ts:67

mode

readonly mode: "create-if-missing";

payer

readonly payer: Address;

owner

readonly owner: Address;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:64

shipId

readonly shipId: number;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:62

source?

readonly optional source?: Address;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:66

---

PlanFleetCrewTransferOptions

Defined in: packages/sage/src/fleets/actions/crew-transfer.ts:18

Direct player authorization and the positive count for ordinary Docked Fleet crew transfer.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetCrewTransferOptions = { authorization, count: 1 };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/crew-transfer.ts:19

count

readonly count: number;

Defined in: packages/sage/src/fleets/actions/crew-transfer.ts:20

---

PlanFleetDockOptions

Defined in: packages/sage/src/fleets/actions/index.ts:123

Inputs for planning one idle-to-docked Fleet transition.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetDockOptions = { authorization };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/index.ts:124

---

PlanFleetRespawnOptions

Defined in: packages/sage/src/fleets/actions/respawn.ts:17

Direct player authorization and the faction CSS System for explicit timed recovery.

Example

declare const authorization: PlanAuthorization, system: Address;
const options: PlanFleetRespawnOptions = { authorization, system };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/respawn.ts:18

system

readonly system: Address;

Defined in: packages/sage/src/fleets/actions/respawn.ts:19

---

PlanFleetSettleArrivalOptions

Defined in: packages/sage/src/fleets/actions/index.ts:192

Explicit authority for a completed Fleet journey, separate from the fee payer.

Requires direct Profile authorization for current Game subwarp. Certificates are not supported for arrival.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetSettleArrivalOptions = { authorization };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/index.ts:193

---

PlanFleetStopSubwarpOptions

Defined in: packages/sage/src/fleets/actions/index.ts:204

Inputs for stopping one Fleet subwarp early.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetStopSubwarpOptions = { authorization };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/index.ts:205

---

PlanFleetUndockOptions

Defined in: packages/sage/src/fleets/actions/index.ts:111

Inputs for planning one docked-to-idle Fleet transition.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetUndockOptions = { authorization };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/index.ts:112

---

PlanFleetWarpLaneOptions

Defined in: packages/sage/src/fleets/actions/index.ts:176

Inputs for planning one explicit connected-system Fleet warp.

Example

declare const authorization: PlanAuthorization;
declare const destinationSystem: Address;
const options: PlanFleetWarpLaneOptions = {
  authorization,
  destinationSystem,
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/fleets/actions/index.ts:177

destinationSystem

readonly destinationSystem: Address;

Defined in: packages/sage/src/fleets/actions/index.ts:178

Type Aliases

FleetDockDebitBounds

type FleetDockDebitBounds =
  | {
  reason:   | DockBoundsUnavailableReason
     | "not-fleet-dock"
     | "multiple-fleet-docks"
     | "combined-plan";
  status: "unavailable";
  toJSON: unknown;
}
  | {
  fleet: Address;
  maximumFleetGrowthBytes: 40;
  maximumProfileDebit: bigint;
  profile: Address;
  profileUnit: "lamports";
  starbasePlayer: Address;
  status: "available";
  transactionFees: "excluded";
  toJSON: unknown;
};

Defined in: packages/sage/src/fleets/actions/dock-bounds.ts:19

Conservative gross Profile storage debit for qualified ordinary docking. Surplus and refunds are not credited; unavailable never implies zero cost.

Example

declare const bounds: FleetDockDebitBounds;
if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);

---

PlanFleetCoordinateMovementOptions

type PlanFleetCoordinateMovementOptions =
  | {
  authorization: PlanAuthorization;
  destination: FleetSnapshot["location"];
  destinationRaw?: never;
}
  | {
  authorization: PlanAuthorization;
  destination?: never;
  destinationRaw: {
     x: bigint;
     y: bigint;
  };
};

Defined in: packages/sage/src/fleets/actions/index.ts:149

Inputs for planning one explicit coordinate-destination Fleet movement.

Choose exactly one representation. destination accepts display numbers and applies the generated I8F56 codec’s rounding. destinationRaw preserves an exact signed-I8F56 value, such as a Star System’s coordinatesRaw.

Example

declare const authorization: PlanAuthorization;
declare const destinationSystem: {
  readonly coordinatesRaw: { readonly x: bigint; readonly y: bigint };
};
const displayOptions: PlanFleetCoordinateMovementOptions = {
  authorization,
  destination: { x: 12, y: -7 },
};
const exactOptions: PlanFleetCoordinateMovementOptions = {
  authorization,
  destinationRaw: destinationSystem.coordinatesRaw,
};

Functions

getFleetDockDebitBounds()

function getFleetDockDebitBounds(plan): FleetDockDebitBounds;

Defined in: packages/sage/src/fleets/actions/dock-bounds.ts:51

Inspects the persisted docking ceiling without network I/O. Inspect individual Plans before combining distinct Fleets. Fresh pre-sign checks are not an atomic on-chain spending cap; state can change before landing.

Parameters

Parameter	Type
plan	Plan

Returns

FleetDockDebitBounds

Example

declare const plan: Plan;
const bounds = getFleetDockDebitBounds(plan);
if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);

---

planAddShipToFleet()

function planAddShipToFleet(
   ctx,
   fleet,
input): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/add-ship.ts:88

Plans one singleton transfer of an exact ship configuration from StarbasePlayer entitlement to an owned Docked Fleet. Follows the program’s assembly rules for ships of any size: each ship must be within the Character’s maximum ship size and its research tags must all be held; the resulting Fleet’s points (XXS 1, XS 4, Small 9, Medium 16, Large 25, Capital 36, Commander 49, Titan 128) must fit both the Character’s Fleet size and the Game limit, with at most one Titan and two Commanders and Titans together. Escrowed hulls of any configuration of the same ship count, as the program re-tags them. Any Starbase with a current StarbasePlayer of the Fleet’s faction works. Configurations that need ship components, and Fleets built under older ship definitions, are not planned yet. The explicit ship ID must be a u16 and the whole ship amount must be 1n through 255n. Uses a direct Profile AUTH key or a manageFleet key scoped to SAGE or the Fleet; a positive Profile rent shortfall additionally requires vault-funding permission. No token transfer or onboarding occurs. A rented Fleet is refused, as is a Fleet whose HP plus pending repair cannot reach its maximum; the program also needs full AP and SP, which recover on timers and stay chain-authoritative. Final stats, research, refresh and outcomes remain chain-authoritative. Simulate before signing. The observed debit ceiling is rechecked before signing and is not an atomic on-chain spending cap. Two assembly Plans for the same Profile cannot compose because they share funds and assembly state.

Parameters

Parameter	Type
ctx	SageContext
fleet	Address
input	PlanAddShipToFleetOptions

Returns

Promise<Plan>

Example

declare const ctx:SageContext, fleet:Address, profile:Address, authority:Address;
const plan = await planAddShipToFleet(ctx,fleet,{authorization:{profile,authority,keyIndex:0},shipId:1,amount:1n});
console.log(plan.describe());

---

planCreateFleet()

function planCreateFleet(ctx, input): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/create-fleet.ts:69

Plans a standalone empty Docked Fleet, without signing or submitting. Derives all account addresses from the configured Game, Profile, exact label and System. Accepted label bytes are preserved. Requires an existing own-faction StarbasePlayer, a direct Profile AUTH or SAGE manageFleet key, and available stored Character capacity. The Profile pays only the Fleet target’s rent shortfall; a non-AUTH key needs drainSolVault only for a positive debit. The observed debit is checked again before signing; it is not an atomic on-chain spending cap. Final rent and funding remain chain-authoritative. No implicit key grants, registration or funding occurs. Final modifier refresh and deployed eligibility remain chain-authoritative: simulate before signing. Creation Plans for the same Character cannot be combined.

Parameters

Parameter	Type
ctx	SageContext
input	PlanCreateFleetOptions

Returns

Promise<Plan>

Example

declare const ctx:SageContext, profile:Address, authority:Address, system:Address;
const plan=await planCreateFleet(ctx,{authorization:{profile,authority,keyIndex:0},system,label:'Scout'});
console.log(plan.describe());

---

planDepositShipsToGame()

function planDepositShipsToGame(
   ctx,
   starbase,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/ship-import.ts:189

Plans importing whole ship tokens into a registered player’s CSS ship escrow. Requires direct Profile AUTH and token-owner authorization. The Profile vault funds any StarbasePlayer storage shortfall; an explicit ATA payer funds optional escrow creation. Fees are separate. No Fleet is created and no signer is retained.

Parameters

Parameter	Type
ctx	SageContext
starbase	ShipImportStarbaseIntent
options	PlanDepositShipsToGameOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const starbase: import('@aephia/atlas-kit/starbases').StarbasePlayerSnapshot;
declare const options: PlanDepositShipsToGameOptions;
const plan = await planDepositShipsToGame(ctx, starbase, options);
console.log(plan.describe());

---

planFleetCompleteRespawn()

function planFleetCompleteRespawn(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/respawn.ts:130

Prepares timed completion only after the stored Respawn end time according to chain Clock. Uses the explicit Respawn-to-Docked route; never pays to bypass the timer. Refresh confirmed state to establish arrival at the faction CSS; simulation is not confirmation.

Parameters

Parameter	Type
ctx	SageContext
fleet	Address
options	PlanFleetRespawnOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext, fleet: Address, options: PlanFleetRespawnOptions;
const plan = await planFleetCompleteRespawn(ctx, fleet, options);
console.log(plan.describe());

---

planFleetDock()

function planFleetDock(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1650

Plans one explicit Fleet dock without signing, simulation, or write RPC.

The planner accepts a loaded idle or refreshable warp Fleet snapshot, resolves the only canonical Character, Star System at its action coordinate, and Starbase Player internally, and returns one inspectable idle-to-docked Plan. A subwarp snapshot is refused: the dock step refreshes the Fleet without its Character and cannot settle a subwarp journey, so settle the arrival or stop the subwarp first.

Docking is admitted when the Starbase Player belongs to the Starbase’s controlling faction, whatever the territory and economics settings. A foreign Starbase Player is refused while territory access is off; foreign docking under territory access and dynamic-faction Starbases are refused as unsupported.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetDockOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetDock(ctx, fleet, { authorization });
console.log(plan.describe());

---

planFleetSettleArrival()

function planFleetSettleArrival(
   ctx,
   fleet,
input): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1365

Plans settlement after chain time confirms the scheduled Fleet journey duration has elapsed.

Game version 2 subwarp requires explicit direct Profile authorization and existing reconciled Career XP accounts. Warp settlement is unsupported. Journeys whose scheduled duration has not elapsed and Idle Fleets fail locally. Planning and execution read fresh accounts; no host clock is used.

Settlement does not guarantee reaching the destination: insufficient Fuel can leave the Fleet Idle short of it. Low Fuel produces a planning-time warning, not a rejection. Inspect refreshed state and location after confirmation. Subwarp settles fuel and XP and may refund released storage rent to the Profile. Warp cooldown remains independent. Fresh checks cannot prevent a concurrent transaction from starting another journey before execution; the authorized instruction could stop that new journey. Intentional early stopping remains the separate planFleetStopSubwarp operation.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
input	PlanFleetSettleArrivalOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetSettleArrival(ctx, fleet, { authorization });
console.log(plan.describe());

---

planFleetStartRespawn()

function planFleetStartRespawn(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/respawn.ts:113

Prepares explicit timed recovery for an owned Idle Fleet, including a zero-Fuel Fleet. Requires Character ATLAS for the current hull recovery fees. Never deposits funds, signs, submits, waits or automatically falls back from movement. Recovery may lose assets.

Parameters

Parameter	Type
ctx	SageContext
fleet	Address
options	PlanFleetRespawnOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext, fleet: Address, options: PlanFleetRespawnOptions;
const plan = await planFleetStartRespawn(ctx, fleet, options);
console.log(plan.describe());

---

planFleetStopSubwarp()

function planFleetStopSubwarp(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1434

Plans an early Fleet subwarp stop without signing, simulation, or write RPC.

This operation stops an in-progress subwarp before arrival. Use planFleetSettleArrival for a trip already known to have completed; callers should not deliberately stop a completed trip. An idle Fleet is still accepted so the program’s benign no-op handles the normal race where subwarp completes between planning and execution.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetStopSubwarpOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetStopSubwarp(ctx, fleet, { authorization });
console.log(plan.describe());

---

planFleetSubwarp()

function planFleetSubwarp(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1307

Plans one explicit Fleet subwarp to a display or exact raw coordinate without movement estimates.

A coordinate outside every Region is deep space and carries no Region hint. A player Fleet may cross deep space, but stopping there needs the Character’s High Risk zone access; NPC Fleets need none.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetCoordinateMovementOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetSubwarp(ctx, fleet, {
  authorization,
  destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
});

---

planFleetUndock()

function planFleetUndock(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1515

Plans one explicit Fleet undock without signing, simulation, or write RPC.

The planner accepts a loaded Fleet snapshot, resolves its canonical Character, docked Star System, and Starbase Player internally, and returns one inspectable docked-to-idle Plan.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetUndockOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetUndock(ctx, fleet, { authorization });
console.log(plan.describe());

---

planFleetWarpLane()

function planFleetWarpLane(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1193

Plans one explicit connected-system Fleet warp without local economics estimates.

The planner resolves the source Star System from the Fleet’s action coordinate, proves connectivity from that System’s decoded connections, and resolves all generated instruction accounts internally. CurrencyCache shared accounting may change; canonical identity/layout and the existing toll-input guards remain checked before signing. Refresh and recreate older Plans to use this guard.

Connectivity does not guarantee eligibility. The program remains authoritative for faction-relationship and destination-risk checks and any ATLAS toll. Tested current PTR routes succeed with empty Fuel tanks. This planner does not estimate lane costs or treat enabled cross-faction economics as blanket permission.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetWarpLaneOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const destinationSystem: Address;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpLane(ctx, fleet, {
  authorization,
  destinationSystem,
});

---

planFleetWarpToCoordinate()

function planFleetWarpToCoordinate(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/index.ts:1332

Plans one explicit Fleet coordinate warp to a display or exact raw coordinate without movement estimates.

A coordinate outside every Region is deep space and carries no Region hint. A player Fleet may cross deep space, but stopping there needs the Character’s High Risk zone access; NPC Fleets need none.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
options	PlanFleetCoordinateMovementOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpToCoordinate(ctx, fleet, {
  authorization,
  destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
});

---

planLoadFleetCrew()

function planLoadFleetCrew(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/crew-transfer.ts:115

Loads an explicit positive u16 crew count from the canonical StarbasePlayer into a directly owned Docked Fleet. Requires a direct Profile key with AUTH, or with the SAGE manage-crew permission scoped to SAGE or this Fleet; current ship definitions; no Character roster; and an absent or exact-neutral Fleet binding. Rented crew are unsupported. Available Starbase crew exclude busy crew; capacity includes required crew and passengers. Planning never signs or submits. This transfer must execute alone.

Parameters

Parameter	Type
ctx	SageContext
fleet	Address
options	PlanFleetCrewTransferOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext, fleet: Address, authorization: PlanAuthorization;
const plan = await planLoadFleetCrew(ctx, fleet, { authorization, count: 1 });
console.log(plan.describe());

---

planUnloadFleetCrew()

function planUnloadFleetCrew(
   ctx,
   fleet,
options): Promise<Plan>;

Defined in: packages/sage/src/fleets/actions/crew-transfer.ts:133

Unloads an explicit positive u16 crew count from a directly owned Docked Fleet into its canonical StarbasePlayer. Unloading every crew member is allowed while Docked; departure requires reloading required crew. Supports the same ordinary-crew and direct-key boundary as loading. Execute separately and refresh after confirmation before preparing another transfer or movement.

Parameters

Parameter	Type
ctx	SageContext
fleet	Address
options	PlanFleetCrewTransferOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext, fleet: Address, authorization: PlanAuthorization;
const plan = await planUnloadFleetCrew(ctx, fleet, { authorization, count: 1 });
console.log(plan.describe());

References

PlanAuthorization

Re-exports PlanAuthorization