cargo/actions

Interfaces

PlanAuthorization

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

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:100

certificate?

readonly optional certificate?: Address;

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

keyIndex

readonly keyIndex: number;

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

profile

readonly profile: Address;

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

---

PlanDepositCargoToGameOptions

Defined in: packages/sage/src/cargo/actions/deposit.ts:42

Exact wallet token units to deposit into an existing player-local Starbase. The owner is the source token owner, independently of the Profile authority. The default source is the owner’s standard associated token account; an explicit existing original Token account may be supplied instead.

Example

declare const authorization: PlanAuthorization;
declare const owner: Address;
const options: PlanDepositCargoToGameOptions = { cargoId: 1, amount: 10n, owner, authorization };

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/cargo/actions/deposit.ts:44

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/cargo/actions/deposit.ts:45

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/cargo/actions/deposit.ts:43

owner

readonly owner: Address;

Defined in: packages/sage/src/cargo/actions/deposit.ts:46

source?

readonly optional source?: Address;

Defined in: packages/sage/src/cargo/actions/deposit.ts:47

---

PlanFleetTransferCargoAtStarbaseOptions

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

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:64

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:62

direction

readonly direction: "toFleet" | "toStarbase";

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

---

PlanFleetTransferCargoWithinFleetOptions

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

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:97

authorization

readonly authorization: PlanAuthorization;

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

cargoId

readonly cargoId: number;

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

from

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

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

to

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

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

---

PlanWithdrawCargoFromGameOptions

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:39

An exact withdrawal to an explicit receiving wallet, independently of Profile authority. destinationAccount permits creating only a missing canonical ATA. An existing destination needs no extra payer signature; custom destinations must exist.

Example

declare const authorization: PlanAuthorization;
declare const recipient: Address;
const options: PlanWithdrawCargoFromGameOptions = {cargoId:3,amount:10n,authorization,recipient};

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:41

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:42

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:40

destination?

readonly optional destination?: Address;

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:44

destinationAccount?

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

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:45

mode

readonly mode: "create-if-missing";

payer

readonly payer: Address;

recipient

readonly recipient: Address;

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:43

Functions

planDepositCargoToGame()

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

Defined in: packages/sage/src/cargo/actions/deposit.ts:72

Plans a wallet-to-game cargo deposit without signing, sending, or creating accounts. Amount is exact raw token units, independent of mint display decimals. Refresh the loaded Starbase before planning; execution checks the retained guards. Profile authority and token owner both sign when they are different addresses. A cargo id new to the Starbase Player adds a cargo line whose storage the program funds from the Profile vault; the Plan states that amount, and a positive one needs Profile AUTH or drainSolVault.

Parameters

Parameter	Type
ctx	SageContext
starbase	StarbasePlayerIntent
options	PlanDepositCargoToGameOptions

Returns

Promise<Plan>

Example

import { planDepositCargoToGame } from '@aephia/atlas-kit/cargo/actions';
import type { SageContext, Address } from '@aephia/atlas-kit/client';
import type { StarbasePlayerSnapshot } from '@aephia/atlas-kit/starbases';
declare const ctx: SageContext;
declare const starbase: StarbasePlayerSnapshot;
declare const authorization: PlanAuthorization;
declare const owner: Address;
const plan = await planDepositCargoToGame(ctx, starbase, {
  cargoId: 1, amount: 10n, authorization, owner,
});
console.log(plan.summary);

---

planFleetTransferCargoAtStarbase()

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

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

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. It also reads the Profile and Rent sysvar to bound the storage the program funds from the Profile vault for cargo lines the transfer adds, net of lines it empties across the Fleet and Starbase Player; a positive amount needs Profile AUTH or drainSolVault. 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:892

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. It reads the Fleet, Profile and Rent sysvar to bound the storage the program funds from the Profile vault when the transfer adds a cargo-hold line; a positive amount needs Profile AUTH or drainSolVault. 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());

---

planWithdrawCargoFromGame()

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

Defined in: packages/sage/src/cargo/actions/withdrawal.ts:69

Plans an exact game-to-wallet withdrawal without signing or submitting. Current verified game/token conversion is limited to zero-decimal cargo mints. The recipient never signs merely to receive tokens. ATA creation is explicit, with storage funding described separately from execution transaction fees. Permissions and the remaining epoch budget stay chain-authoritative.

Parameters

Parameter	Type
ctx	SageContext
starbase	StarbasePlayerIntent
options	PlanWithdrawCargoFromGameOptions

Returns

Promise<Plan>

Example

import {planWithdrawCargoFromGame} from '@aephia/atlas-kit/cargo/actions';
import type {SageContext,Address} from '@aephia/atlas-kit/client';
import type {StarbasePlayerSnapshot} from '@aephia/atlas-kit/starbases';
declare const ctx:SageContext;
declare const starbase:StarbasePlayerSnapshot;
declare const authorization:PlanAuthorization;
declare const recipient:Address;
const plan=await planWithdrawCargoFromGame(ctx,starbase,{cargoId:3,amount:10n,authorization,recipient});
console.log(plan.summary);