claim-stakes/actions

Interfaces

ClaimStakeFleetTransferCargoRequest

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

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

cargoId

readonly cargoId: number;

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

---

PlanCancelClaimStakeBuildingChangesOptions

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

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

---

PlanClaimStakeBuildingChangesOptions

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

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

buildingChanges

readonly buildingChanges: readonly ClaimStakeBuildingChange[];

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

---

PlanDeconstructClaimStakeOptions

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

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

---

PlanFinalizeClaimStakeBuildingChangesOptions

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

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

---

PlanPlaceClaimStakeOptions

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

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

claimStake

readonly claimStake: Address;

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

claimStakeDefinitionId

readonly claimStakeDefinitionId: number;

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

hubBuildingId

readonly hubBuildingId: number;

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

initialRentAmount

readonly initialRentAmount: bigint;

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

---

PlanRecoverClaimStakeFleetTransferOptions

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

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

authorization

readonly authorization: PlanAuthorization;

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

---

PlanStartClaimStakeFleetTransferOptions

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

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

load

readonly load: readonly ClaimStakeFleetTransferCargoRequest[];

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

unload

readonly unload: readonly ClaimStakeFleetTransferCargoRequest[];

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

---

PlanTopUpClaimStakeRentOptions

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

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

authorization

readonly authorization: PlanAuthorization;

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

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

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

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.

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

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, crew, and known construction cargo. Rent synchronization and the final concurrent sequence race remain chain-authoritative.

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

Plans deconstruction of one owned active Claim Stake.

The planner derives the current Planet chronology index and exact plot bucket from the Claim Stake definition tier and fresh Body plot matrix. 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.

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

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.

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

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.

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

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

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. The chain remains authoritative for range, duration, permission bits, concurrent state changes, and transfer arithmetic.

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

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

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