claim-stakes/actions

Interfaces

ClaimStakeFleetTransferCargoRequest

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

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

cargoId

readonly cargoId: number;

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

PlanCancelClaimStakeBuildingChangesOptions

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

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

PlanClaimStakeBuildingChangesOptions

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

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

buildingChanges

readonly buildingChanges: readonly ClaimStakeBuildingChange[];

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

PlanDeconstructClaimStakeOptions

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

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

PlanFinalizeClaimStakeBuildingChangesOptions

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

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

PlanPlaceClaimStakeOptions

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

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

initialRentAmount is an optional positive raw unsigned-u64 rent deposit; omit it to place the stake with no rent. 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:182

claimStake

readonly claimStake: Address;

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

claimStakeDefinitionId

readonly claimStakeDefinitionId: number;

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

hubBuildingId

readonly hubBuildingId: number;

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

initialRentAmount?

readonly optional initialRentAmount?: bigint;

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

PlanRecoverClaimStakeFleetTransferOptions

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

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

authorization

readonly authorization: PlanAuthorization;

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

PlanStartClaimStakeFleetTransferOptions

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

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

load

readonly load: readonly ClaimStakeFleetTransferCargoRequest[];

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

unload

readonly unload: readonly ClaimStakeFleetTransferCargoRequest[];

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

PlanTopUpClaimStakeRentOptions

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

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

authorization

readonly authorization: PlanAuthorization;

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

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

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

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.

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

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.

Entering a design adds the design state and an entry for each building id the design does not yet hold. The program funds that growth, up to the stake’s rent floor, from the Profile vault with the signing key; the Plan bounds the debit with the same key and balance checks as placement.

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

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

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

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.

Finalization can draw Profile storage this Plan does not bound: a removed building’s refund can open a Starbase Player cargo line, and a final layout that produces a new resource raises the stake’s rent floor. The program funds both from the Profile vault with the signing key, so simulate before signing.

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.

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

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 also checks the Character’s productive plot count and tier limits, the bundled hub’s tags against the Planet and Claim Stake definition, and that the Character’s ATLAS covers the placement fee plus any initial rent. 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.

The program funds the new stake to its rent floor, the size it can reach once Deactivated with a cargo line for each resource it produces, and the Planet’s claimed plot from the Profile vault with the signing key. The Plan bounds that debit; when it is positive the key must be Profile AUTH or hold drainSolVault, and the Profile needs that many lamports above its rent reserve. Execution checks again before 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:3063

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

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.

The Fleet stores the requested load and unload lines while the transfer runs. The program settles the Fleet and stake together: the stake’s lamports above its rent floor fund the Fleet first and the Profile vault, with the signing key, funds the rest. The Plan bounds that debit with the same key and balance checks as placement.

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

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

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.

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