claim-stakes/actions

Interfaces

ClaimStakeFleetTransferCargoRequest

Defined in: packages/sage/src/claim-stakes/actions/index.ts:299

One exact raw cargo request for starting a Claim Stake Fleet transfer.

Example

const request: ClaimStakeFleetTransferCargoRequest = {
  cargoId: 3,
  amount: 25n,
};

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:301

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:300

---

PlanCancelClaimStakeBuildingChangesOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:255

Exact inputs for cancelling one owned Claim Stake building design.

Example

declare const authorization: PlanAuthorization;
const options: PlanCancelClaimStakeBuildingChangesOptions = {
  authorization,
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:256

---

PlanClaimStakeBuildingChangesOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:226

Exact inputs for changing one owned Claim Stake’s building design.

buildingChanges is a non-empty dense list with one positive add/remove quantity per building id.

Example

declare const authorization: PlanAuthorization;
const options: PlanClaimStakeBuildingChangesOptions = {
  authorization,
  buildingChanges: [{ buildingId: 9, kind: 'add', quantity: 2 }],
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:227

buildingChanges

readonly buildingChanges: readonly ClaimStakeBuildingChange[];

Defined in: packages/sage/src/claim-stakes/actions/index.ts:228

---

PlanDeconstructClaimStakeOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:267

Exact inputs for deconstructing one owned active Claim Stake.

Example

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

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:268

---

PlanFinalizeClaimStakeBuildingChangesOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:241

Exact inputs for finalizing one owned Claim Stake building design.

Example

declare const authorization: PlanAuthorization;
const options: PlanFinalizeClaimStakeBuildingChangesOptions = {
  authorization,
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:242

---

PlanPlaceClaimStakeOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:178

Exact address-only inputs for placing one Claim Stake and its bundled hub.

initialRentAmount is a positive raw unsigned-u64 amount. claimStake is a new caller-created signer whose public address is retained without key material.

Example

declare const authorization: PlanAuthorization;
declare const claimStake: Address;
const options: PlanPlaceClaimStakeOptions = {
  authorization,
  claimStake,
  claimStakeDefinitionId: 2,
  hubBuildingId: 21,
  initialRentAmount: 500_000_000n,
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:179

claimStake

readonly claimStake: Address;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:180

claimStakeDefinitionId

readonly claimStakeDefinitionId: number;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:181

hubBuildingId

readonly hubBuildingId: number;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:182

initialRentAmount

readonly initialRentAmount: bigint;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:183

---

PlanRecoverClaimStakeFleetTransferOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:340

Exact inputs for recovering one provably stuck Claim Stake Fleet transfer.

atUnixSeconds is an explicit non-negative Unix timestamp used to prove the transfer lock has elapsed. The planner never reads a local clock.

Example

declare const authorization: PlanAuthorization;
const options: PlanRecoverClaimStakeFleetTransferOptions = {
  atUnixSeconds: 1_700_000_100n,
  authorization,
};

Properties

atUnixSeconds

readonly atUnixSeconds: bigint;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:341

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:342

---

PlanStartClaimStakeFleetTransferOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:320

Exact bidirectional cargo inputs for starting one Claim Stake Fleet transfer.

load moves cargo from the Claim Stake to the Fleet; unload moves cargo from the Fleet to the Claim Stake. At least one list must contain a request, and each cargo id may appear only once across both dense lists.

Example

declare const authorization: PlanAuthorization;
const options: PlanStartClaimStakeFleetTransferOptions = {
  authorization,
  load: [{ cargoId: 3, amount: 25n }],
  unload: [{ cargoId: 1, amount: 10n }],
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:321

load

readonly load: readonly ClaimStakeFleetTransferCargoRequest[];

Defined in: packages/sage/src/claim-stakes/actions/index.ts:322

unload

readonly unload: readonly ClaimStakeFleetTransferCargoRequest[];

Defined in: packages/sage/src/claim-stakes/actions/index.ts:323

---

PlanTopUpClaimStakeRentOptions

Defined in: packages/sage/src/claim-stakes/actions/index.ts:284

Exact inputs for topping up one owned placed Claim Stake’s rent.

amount is a positive raw unsigned-u64 amount, not a display ATLAS value.

Example

declare const authorization: PlanAuthorization;
const options: PlanTopUpClaimStakeRentOptions = {
  amount: 500_000_000n,
  authorization,
};

Properties

amount

readonly amount: bigint;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:285

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:286

Type Aliases

ClaimStakeBuildingChange

type ClaimStakeBuildingChange =
  | {
  buildingId: number;
  kind: "add";
  quantity: number;
}
  | {
  buildingId: number;
  kind: "remove";
  quantity: number;
};

Defined in: packages/sage/src/claim-stakes/actions/index.ts:200

One bounded Claim Stake building addition or removal.

The positive quantity is translated to the generated instruction’s signed delta. Each building id may appear only once in a plan.

Example

const change: ClaimStakeBuildingChange = {
  buildingId: 9,
  kind: 'add',
  quantity: 2,
};

Functions

planCancelClaimStakeBuildingChanges()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:2065

Plans cancellation of one owned Claim Stake building design.

The planner requires a fresh design state and a coherent configured Game/Claim Stake/Planet/System/Starbase Player graph. The program re-synchronizes rent at execution and returns the Claim Stake to active state; rent arithmetic and concurrent state transitions remain chain-authoritative.

Requires Game 2 and its existing canonical Claim Stake XP ledger. Missing XP state must be repaired outside this Plan; no accounts are created.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history.

Parameters

Parameter	Type
ctx	SageContext
stake	ClaimStakeSnapshot
input	PlanCancelClaimStakeBuildingChangesOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planCancelClaimStakeBuildingChanges(ctx, stake, {
  authorization,
});
console.log(plan.describe());

---

planClaimStakeBuildingChanges()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:1458

Plans one exact set of additions/removals for an owned active/design Claim Stake.

The planner verifies the fresh Claim Stake, definition sequences, canonical Profile/Character/Body/System/Starbase Player graph, optional FactionOwnership sidecar, building quantities, slots, Starbase Player crew, non-negative power, a single unremovable hub of quantity one, building tags provided by the Claim Stake definition, the Planet and the buildings, and known construction cargo. A stake whose stored construction time is still running is refused; that time advances only on a production tick. Construction cargo is debited from the Starbase Player’s Starbase cargo at finalization, never from the Claim Stake’s own storage, so the planner checks the fresh Starbase Player pod. Rent synchronization and the final concurrent sequence race remain chain-authoritative.

Requires Game 2 and its existing canonical Claim Stake XP ledger. Missing XP state must be repaired outside this Plan; no accounts are created.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history.

Parameters

Parameter	Type
ctx	SageContext
stake	ClaimStakeSnapshot
input	PlanClaimStakeBuildingChangesOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const stake: ClaimStakeSnapshot;
declare const options: PlanClaimStakeBuildingChangesOptions;
const plan = await planClaimStakeBuildingChanges(ctx, stake, options);
console.log(plan.describe());

---

planDeconstructClaimStake()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:2187

Plans deconstruction of one owned active Claim Stake.

The planner derives the plot level from the fresh Planet plot row that records the stake, and the index from its position in that row. The only remaining building must be the definition-compatible zero-cost bundled hub, which deconstruction discards. Rent settlement, cargo return, account closure, and concurrent races remain chain-authoritative; the Plan does not estimate a refund.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history. Deconstruction also requires the canonical Currency Cache and closes the Claim Stake’s XP ledger; a Claim Stake without a ledger accrued no XP.

Parameters

Parameter	Type
ctx	SageContext
stake	ClaimStakeSnapshot
input	PlanDeconstructClaimStakeOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planDeconstructClaimStake(ctx, stake, { authorization });
console.log(plan.describe());

---

planFinalizeClaimStakeBuildingChanges()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:1899

Plans finalization of one owned Claim Stake building design.

The planner requires a fresh design state, a coherent configured Game/Character/Planet/System/Starbase Player graph, the canonical CurrencyCache, and a known positive rent balance. Rent timing and the final crew/building validation remain chain-authoritative.

Requires Game 2 and its existing canonical Claim Stake XP ledger. The Character XP budget and configuration must also be reconciled. Missing XP state must be repaired outside this Plan; no accounts are created.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history.

Parameters

Parameter	Type
ctx	SageContext
stake	ClaimStakeSnapshot
input	PlanFinalizeClaimStakeBuildingChangesOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFinalizeClaimStakeBuildingChanges(ctx, stake, {
  authorization,
});
// The program re-synchronizes rent at execution.
console.log(plan.describe());

---

planPlaceClaimStake()

function planPlaceClaimStake(
   ctx,
   body,
   player,
input): Promise<Plan>;

Defined in: packages/sage/src/claim-stakes/actions/index.ts:767

Plans placement of one Claim Stake with its exact bundled hub.

The planner validates the configured Game/Profile/Character/System/Body graph, current catalog membership, known plot/cargo/crew availability, and absence of the caller-created Claim Stake account. It returns one inert Plan; permissions, placement races, rent arithmetic, and program capacity remain chain-authoritative.

The new Claim Stake’s rent settlement authority must not exist and stays guarded absent until signing.

Parameters

Parameter	Type
ctx	SageContext
body	CelestialBodySnapshot
player	StarbasePlayerSnapshot
input	PlanPlaceClaimStakeOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const body: CelestialBodySnapshot;
declare const player: StarbasePlayerSnapshot;
declare const options: PlanPlaceClaimStakeOptions;
const plan = await planPlaceClaimStake(ctx, body, player, options);
console.log(plan.describe());

---

planRecoverClaimStakeFleetTransfer()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:2929

Plans owner-authorized recovery of one provably non-executable Claim Stake transfer.

Recovery is available only after the explicit transfer lock time and only when fresh Fleet/Claim Stake cargo and Game definition state proves a source shortfall, invalid queued cargo id, or destination overflow. An executable transfer is rejected so callers use the permissionless normal exit instead. Recovery returns the Fleet to idle without moving cargo or changing the Claim Stake.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
stake	ClaimStakeSnapshot
input	PlanRecoverClaimStakeFleetTransferOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, {
  atUnixSeconds: 1_700_000_100n,
  authorization,
});
console.log(plan.describe());

---

planStartClaimStakeFleetTransfer()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:2656

Plans the start of one Fleet transfer to an owned active Claim Stake.

The planner validates the shared Profile/Game, idle Fleet with normalized crew, active Claim Stake, canonical Planet/System/Starbase Player graph, exact source balances, exact destination capacities, and an optional present FleetCrewBinding. Both legs use the Fleet cargo hold only: loaded Fuel and Ammunition arrive in the cargo hold and consume cargo capacity, and unloads are sourced from the cargo hold, never from the fuel tank or ammo bank. The chain remains authoritative for range, duration, permission bits, concurrent state changes, and transfer arithmetic.

Requires Game 2 and its existing canonical Claim Stake XP ledger. Missing XP state must be repaired outside this Plan; no accounts are created.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
stake	ClaimStakeSnapshot
input	PlanStartClaimStakeFleetTransferOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planStartClaimStakeFleetTransfer(ctx, fleet, stake, {
  authorization,
  load: [{ cargoId: 3, amount: 25n }],
  unload: [{ cargoId: 1, amount: 10n }],
});
console.log(plan.describe());

---

planTopUpClaimStakeRent()

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

Defined in: packages/sage/src/claim-stakes/actions/index.ts:2448

Plans one exact raw rent top-up for an owned Claim Stake.

Active, design and Deactivated (rent-delinquent) stakes all accept a top-up; topping up a Deactivated stake is how its owner keeps it from eviction. The planner validates the fresh Claim Stake and its canonical Profile/Character/Planet/System/Starbase Player graph, plus the Character’s known raw ATLAS balance. Permission checks, concurrent balance changes, rent arithmetic, and duration purchased remain chain-authoritative.

Requires Disabled rent: the Game’s rent catalog and the Claim Stake’s rent settlement authority must not exist, and both stay guarded absent until signing. The instruction carries no rent history.

Parameters

Parameter	Type
ctx	SageContext
stake	ClaimStakeSnapshot
input	PlanTopUpClaimStakeRentOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const stake: ClaimStakeSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planTopUpClaimStakeRent(ctx, stake, {
  amount: 500_000_000n,
  authorization,
});
console.log(plan.describe());

References

PlanAuthorization

Re-exports PlanAuthorization