cargo/actions

Interfaces

PlanAuthorization

Defined in: packages/sage/src/internal/planning/authorization-adapter.ts:27

Address-only authorization retained by planning before execution binds signers.

Example

declare const profile: Address;
declare const authority: Address;
const authorization: PlanAuthorization = {
  profile,
  authority,
  keyIndex: 0,
};

Properties

authority

readonly authority: Address;

Defined in: packages/sage/src/internal/planning/authorization-adapter.ts:29

certificate?

readonly optional certificate?: Address;

Defined in: packages/sage/src/internal/planning/authorization-adapter.ts:31

keyIndex

readonly keyIndex: number;

Defined in: packages/sage/src/internal/planning/authorization-adapter.ts:30

profile

readonly profile: Address;

Defined in: packages/sage/src/internal/planning/authorization-adapter.ts:28

---

PlanFleetTransferCargoAtStarbaseOptions

Defined in: packages/sage/src/cargo/actions/index.ts:59

Inputs for one explicit Fleet/player-Starbase cargo transfer.

Every quantity is a positive raw on-chain bigint. Ammo and fuel are bounded by signed i64 because direction is encoded by sign; cargo-hold quantities use unsigned u64 and cargo ids use unsigned u16.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetTransferCargoAtStarbaseOptions = {
  authorization,
  direction: 'toFleet',
  amounts: {
    ammo: 25n,
    cargoHold: [{ cargoId: 3, amount: 2n }],
  },
};

Properties

amounts

readonly amounts: {
  ammo?: bigint;
  cargoHold?: readonly {
     amount: bigint;
     cargoId: number;
  }[];
  fuel?: bigint;
};

Defined in: packages/sage/src/cargo/actions/index.ts:62

ammo?

readonly optional ammo?: bigint;

cargoHold?

readonly optional cargoHold?: readonly {
  amount: bigint;
  cargoId: number;
}[];

fuel?

readonly optional fuel?: bigint;

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/cargo/actions/index.ts:60

direction

readonly direction: "toFleet" | "toStarbase";

Defined in: packages/sage/src/cargo/actions/index.ts:61

---

PlanFleetTransferCargoWithinFleetOptions

Defined in: packages/sage/src/cargo/actions/index.ts:90

Inputs for moving one exact cargo quantity between two pods in one Fleet.

The amount is a positive raw on-chain unsigned-u64 bigint; the cargo id is an unsigned-u16 integer. Pod names select the Fleet snapshot’s nested ammo, fuel, or cargo-hold inventory without accepting CargoPod account addresses.

Example

declare const authorization: PlanAuthorization;
const options: PlanFleetTransferCargoWithinFleetOptions = {
  amount: 5n,
  authorization,
  cargoId: 2,
  from: 'ammo',
  to: 'cargoHold',
};

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/cargo/actions/index.ts:95

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/cargo/actions/index.ts:91

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/cargo/actions/index.ts:94

from

readonly from: "cargoHold" | "fuel" | "ammo";

Defined in: packages/sage/src/cargo/actions/index.ts:92

to

readonly to: "cargoHold" | "fuel" | "ammo";

Defined in: packages/sage/src/cargo/actions/index.ts:93

Functions

planFleetTransferCargoAtStarbase()

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

Defined in: packages/sage/src/cargo/actions/index.ts:600

Plans one bidirectional Fleet/player-Starbase cargo transfer without signing or RPC writes.

The caller supplies only gameplay direction and positive raw-unit quantities. Planning directly re-reads the Fleet, canonical Character, and derived StarbasePlayer; checks known source balances (aggregated by cargo id for the shared Starbase inventory) and, when loading the Fleet, exact ammo/fuel/cargo capacity; and returns one inspectable instruction. The chain remains authoritative for state races, crew normalization, faction policy, Profile permission bits including MANAGE_FLEET_CARGO, and program arithmetic. Starbase destination capacity is not inferred because the shipped StarbasePlayer read exposes no total-capacity field.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
input	PlanFleetTransferCargoAtStarbaseOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetTransferCargoAtStarbase(ctx, fleet, {
  authorization,
  direction: 'toStarbase',
  amounts: { fuel: 10n },
});
console.log(plan.describe());

---

planFleetTransferCargoWithinFleet()

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

Defined in: packages/sage/src/cargo/actions/index.ts:972

Plans one exact cargo transfer between two nested pods in one Fleet.

The caller supplies pod names, one unsigned-u16 cargo id, and one positive raw unsigned-u64 amount. Planning uses only the supplied Fleet snapshot for pod identities, resolved cargo ids, balances, and ammo/fuel/cargo-hold capacity. It accepts idle, docked, and Claim Stake transfer states and returns one signer-free, inspectable instruction. The chain remains authoritative for state races, Profile permission bits including MANAGE_FLEET_CARGO, and program arithmetic.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
input	PlanFleetTransferCargoWithinFleetOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetTransferCargoWithinFleet(ctx, fleet, {
  amount: 5n,
  authorization,
  cargoId: fleet.ammo.id,
  from: 'ammo',
  to: 'cargoHold',
});
console.log(plan.describe());