identity

Interfaces

CharacterAccountData

Defined in: packages/sage/src/internal/c4/character.ts:158

SDK-owned decoded Character data.

Example

declare const character: CharacterAccountData;
const atlas = character.atlas;

Properties

atlas

readonly atlas: number;

Defined in: packages/sage/src/internal/c4/character.ts:169

atlasRaw

readonly atlasRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:168

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/character.ts:162

checkIn

readonly checkIn: {
  lastCheckInTime: bigint;
  streak: number;
};

Defined in: packages/sage/src/internal/c4/character.ts:163

lastCheckInTime

readonly lastCheckInTime: bigint;

streak

readonly streak: number;

counts

readonly counts: {
  claimStakes: number;
  craftingHabs: number;
  fleets: number;
};

Defined in: packages/sage/src/internal/c4/character.ts:170

claimStakes

readonly claimStakes: number;

craftingHabs

readonly craftingHabs: number;

fleets

readonly fleets: number;

game

readonly game: Address;

Defined in: packages/sage/src/internal/c4/character.ts:161

modifiers

readonly modifiers: CharacterModifiersData;

Defined in: packages/sage/src/internal/c4/character.ts:181

pilotXpBudget

readonly pilotXpBudget: {
  available: number;
  fractionalCarry: number;
  fractionalCarryRaw: bigint;
  lastAccrualTime: bigint;
};

Defined in: packages/sage/src/internal/c4/character.ts:175

available

readonly available: number;

fractionalCarry

readonly fractionalCarry: number;

fractionalCarryRaw

readonly fractionalCarryRaw: bigint;

lastAccrualTime

readonly lastAccrualTime: bigint;

playerProfile

readonly playerProfile: Address;

Defined in: packages/sage/src/internal/c4/character.ts:160

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/character.ts:159

xp

readonly xp: CharacterXpData;

Defined in: packages/sage/src/internal/c4/character.ts:167

---

CharacterModifierData

Defined in: packages/sage/src/internal/c4/character.ts:98

SDK-owned translation of Character modifier values.

Example

declare const modifiers: CharacterModifierData;
const shipCapacityPerFleet = modifiers.fleetSize;
const maximumFleetCount = modifiers.fleetConcurrency;

Properties

cargoCategories

readonly cargoCategories: readonly number[];

Defined in: packages/sage/src/internal/c4/character.ts:129

craftingEfficiencyModifier

readonly craftingEfficiencyModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:111

craftingEfficiencyModifierRaw

readonly craftingEfficiencyModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:112

craftingJobConcurrencyBonus

readonly craftingJobConcurrencyBonus: number;

Defined in: packages/sage/src/internal/c4/character.ts:115

craftingTimeModifier

readonly craftingTimeModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:113

craftingTimeModifierRaw

readonly craftingTimeModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:114

enemyFactionZoneAccess

readonly enemyFactionZoneAccess: boolean;

Defined in: packages/sage/src/internal/c4/character.ts:121

fleetConcurrency

readonly fleetConcurrency: number;

Defined in: packages/sage/src/internal/c4/character.ts:100

fleetSize

readonly fleetSize: number;

Defined in: packages/sage/src/internal/c4/character.ts:99

maxDailyStreakLength

readonly maxDailyStreakLength: number;

Defined in: packages/sage/src/internal/c4/character.ts:122

maxProductivePlots

readonly maxProductivePlots: number;

Defined in: packages/sage/src/internal/c4/character.ts:119

maxProductivePlotTier?

readonly optional maxProductivePlotTier?: 1 | 5 | 2 | 4 | 3;

Defined in: packages/sage/src/internal/c4/character.ts:118

maxResidentialPlots

readonly maxResidentialPlots: number;

Defined in: packages/sage/src/internal/c4/character.ts:117

maxResidentialPlotTier?

readonly optional maxResidentialPlotTier?: 1 | 5 | 2 | 4 | 3;

Defined in: packages/sage/src/internal/c4/character.ts:116

maxShipSize

readonly maxShipSize: ShipSize;

Defined in: packages/sage/src/internal/c4/character.ts:123

rareMineralDiscovery

readonly rareMineralDiscovery: readonly RareMineralDiscoveryData[];

Defined in: packages/sage/src/internal/c4/character.ts:130

researchTags

readonly researchTags: readonly number[];

Defined in: packages/sage/src/internal/c4/character.ts:128

respawnTimeModifier

readonly respawnTimeModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:101

respawnTimeModifierRaw

readonly respawnTimeModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:102

scanCoolDownModifier

readonly scanCoolDownModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:126

scanCoolDownModifierRaw

readonly scanCoolDownModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:127

scanPowerModifier

readonly scanPowerModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:124

scanPowerModifierRaw

readonly scanPowerModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:125

securityZoneAccess

readonly securityZoneAccess: RiskZoneAccess;

Defined in: packages/sage/src/internal/c4/character.ts:120

subwarpSpeedModifier

readonly subwarpSpeedModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:107

subwarpSpeedModifierRaw

readonly subwarpSpeedModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:108

warpCooldownModifier

readonly warpCooldownModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:109

warpCooldownModifierRaw

readonly warpCooldownModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:110

warpLaneFeeModifier

readonly warpLaneFeeModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:103

warpLaneFeeModifierRaw

readonly warpLaneFeeModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:104

warpSpeedModifier

readonly warpSpeedModifier: number;

Defined in: packages/sage/src/internal/c4/character.ts:105

warpSpeedModifierRaw

readonly warpSpeedModifierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:106

---

CharacterModifiersData

Defined in: packages/sage/src/internal/c4/character.ts:140

SDK-owned Character modifier state from the Character account.

Example

declare const modifiers: CharacterModifiersData;
const nodes = modifiers.unlockedNodes;

Properties

nodeLevels

readonly nodeLevels: readonly {
  level: number;
  nodeId: number;
}[];

Defined in: packages/sage/src/internal/c4/character.ts:144

seqId

readonly seqId: number;

Defined in: packages/sage/src/internal/c4/character.ts:141

unlockedNodes

readonly unlockedNodes: readonly number[];

Defined in: packages/sage/src/internal/c4/character.ts:143

unupdatedCount

readonly unupdatedCount: number;

Defined in: packages/sage/src/internal/c4/character.ts:142

values

readonly values: CharacterModifierData;

Defined in: packages/sage/src/internal/c4/character.ts:148

---

CharacterProgressionSnapshot

Defined in: packages/sage/src/identity/index.ts:144

Character XP and pilot state joined to sequence-matched Game XP rules.

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const progression: CharacterProgressionSnapshot =
  await getCharacterProgressionForProfile(ctx, profileAddress);
console.log(progression.xp.pilot.level);

Properties

character

readonly character: EntityRef<"character">;

Defined in: packages/sage/src/identity/index.ts:146

kind

readonly kind: "characterProgression";

Defined in: packages/sage/src/identity/index.ts:145

pilotXpBudget

readonly pilotXpBudget: {
  available: number;
  fractionalCarry: number;
  fractionalCarryRaw: bigint;
  lastAccrualTime: bigint;
};

Defined in: packages/sage/src/identity/index.ts:148

available

readonly available: number;

fractionalCarry

readonly fractionalCarry: number;

fractionalCarryRaw

readonly fractionalCarryRaw: bigint;

lastAccrualTime

readonly lastAccrualTime: bigint;

xp

readonly xp: CharacterXpData;

Defined in: packages/sage/src/identity/index.ts:147

xpDefinitions

readonly xpDefinitions: GameXpDefinitionsSectionData;

Defined in: packages/sage/src/identity/index.ts:149

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/index.ts:150

Returns

unknown

---

CharacterResearchState

Defined in: packages/sage/src/identity/research-state.ts:22

Display balances derived from one Character, not research purchase eligibility. Sequences describe the input; no current Game definitions are consulted.

Example

declare const state: CharacterResearchState;
console.log(state.careers.mining.researchPointsAvailable, state.renown.available);

Properties

careers

readonly careers: Readonly<Record<typeof careers[number], {
  earnedXp: bigint;
  level: number;
  researchPointsAvailable: bigint;
  researchPointsSpent: bigint;
}>>;

Defined in: packages/sage/src/identity/research-state.ts:27

characterAddress

readonly characterAddress: Address;

Defined in: packages/sage/src/identity/research-state.ts:23

nodes

readonly nodes: readonly {
  level: number;
  nodeId: number;
}[];

Defined in: packages/sage/src/identity/research-state.ts:48

Acquired nodes only. Stored levels are reported as-is, including 0; only a missing entry defaults to 1. This preserves observed state rather than applying the official client’s minimum-1 sync-step estimate.

pendingNodeUpdates

readonly pendingNodeUpdates: number;

Defined in: packages/sage/src/identity/research-state.ts:26

renown

readonly renown: {
  available: bigint;
  careerLevelCarry: number;
  earned: bigint;
  level: number;
  spent: bigint;
};

Defined in: packages/sage/src/identity/research-state.ts:38

available

readonly available: bigint;

careerLevelCarry

readonly careerLevelCarry: number;

earned

readonly earned: bigint;

level

readonly level: number;

spent

readonly spent: bigint;

researchSequenceId

readonly researchSequenceId: number;

Defined in: packages/sage/src/identity/research-state.ts:25

xpSequenceId

readonly xpSequenceId: number;

Defined in: packages/sage/src/identity/research-state.ts:24

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/research-state.ts:52

Returns

unknown

---

CharacterSnapshot

Defined in: packages/sage/src/identity/index.ts:123

Immutable Character snapshot derived from a Player Profile and Game.

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const character: CharacterSnapshot = await getCharacterForProfile(ctx, profileAddress);
console.log(character.profile.address);

Extends

• Omit<CharacterAccountData, "playerProfile">

Extended by

• CharacterView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/identity/index.ts:128

atlas

readonly atlas: number;

Defined in: packages/sage/src/internal/c4/character.ts:169

Inherited from

CharacterAccountData.atlas

atlasRaw

readonly atlasRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:168

Inherited from

CharacterAccountData.atlasRaw

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/character.ts:162

Inherited from

CharacterAccountData.bump

checkIn

readonly checkIn: {
  lastCheckInTime: bigint;
  streak: number;
};

Defined in: packages/sage/src/internal/c4/character.ts:163

lastCheckInTime

readonly lastCheckInTime: bigint;

streak

readonly streak: number;

Inherited from

CharacterAccountData.checkIn

counts

readonly counts: {
  claimStakes: number;
  craftingHabs: number;
  fleets: number;
};

Defined in: packages/sage/src/internal/c4/character.ts:170

claimStakes

readonly claimStakes: number;

craftingHabs

readonly craftingHabs: number;

fleets

readonly fleets: number;

Inherited from

CharacterAccountData.counts

game

readonly game: Address;

Defined in: packages/sage/src/internal/c4/character.ts:161

Inherited from

CharacterAccountData.game

kind

readonly kind: "character";

Defined in: packages/sage/src/identity/index.ts:127

modifiers

readonly modifiers: CharacterModifiersData;

Defined in: packages/sage/src/internal/c4/character.ts:181

Inherited from

CharacterAccountData.modifiers

pilotXpBudget

readonly pilotXpBudget: {
  available: number;
  fractionalCarry: number;
  fractionalCarryRaw: bigint;
  lastAccrualTime: bigint;
};

Defined in: packages/sage/src/internal/c4/character.ts:175

available

readonly available: number;

fractionalCarry

readonly fractionalCarry: number;

fractionalCarryRaw

readonly fractionalCarryRaw: bigint;

lastAccrualTime

readonly lastAccrualTime: bigint;

Inherited from

CharacterAccountData.pilotXpBudget

profile

readonly profile: EntityRef<"profile">;

Defined in: packages/sage/src/identity/index.ts:129

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/character.ts:159

Inherited from

CharacterAccountData.version

xp

readonly xp: CharacterXpData;

Defined in: packages/sage/src/internal/c4/character.ts:167

Inherited from

CharacterAccountData.xp

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/index.ts:130

Returns

unknown

---

CharacterXpCategoryData

Defined in: packages/sage/src/internal/c4/character.ts:27

SDK-owned XP values for one Character category.

Example

declare const category: CharacterXpCategoryData;
const level = category.level;

Properties

earned

readonly earned: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:29

level

readonly level: number;

Defined in: packages/sage/src/internal/c4/character.ts:30

spent

readonly spent: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:28

---

CharacterXpData

Defined in: packages/sage/src/internal/c4/character.ts:40

SDK-owned Character XP state.

Example

declare const xp: CharacterXpData;
const pilotLevel = xp.pilot.level;

Properties

building

readonly building: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:47

combat

readonly combat: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:49

councilRank

readonly councilRank: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:42

councilRankLevelCarry

readonly councilRankLevelCarry: number;

Defined in: packages/sage/src/internal/c4/character.ts:50

crafting

readonly crafting: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:48

dailyXp

readonly dailyXp: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:43

dataRunner

readonly dataRunner: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:45

mining

readonly mining: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:46

pilot

readonly pilot: CharacterXpCategoryData;

Defined in: packages/sage/src/internal/c4/character.ts:44

seqId

readonly seqId: number;

Defined in: packages/sage/src/internal/c4/character.ts:41

---

ProfileAccountData

Defined in: packages/sage/src/internal/c4/identity.ts:54

SDK-owned decoded Player Profile data.

Example

declare const profile: ProfileAccountData;
const keys = profile.keys;

Extended by

• ProfileSnapshot

Properties

authKeyCount

readonly authKeyCount: number;

Defined in: packages/sage/src/internal/c4/identity.ts:56

createdAt

readonly createdAt: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:59

keys

readonly keys: readonly ProfileKeyData[];

Defined in: packages/sage/src/internal/c4/identity.ts:60

keyThreshold

readonly keyThreshold: number;

Defined in: packages/sage/src/internal/c4/identity.ts:57

nextSeqId

readonly nextSeqId: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:58

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/identity.ts:55

---

ProfileKeyData

Defined in: packages/sage/src/internal/c4/identity.ts:38

SDK-owned representation of one Player Profile key.

Example

declare const key: ProfileKeyData;
const expiresAt = key.expiresAt;

Properties

address

readonly address: Address;

Defined in: packages/sage/src/internal/c4/identity.ts:39

expiresAt?

readonly optional expiresAt?: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:42

expiresAtRaw

readonly expiresAtRaw: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:41

permissions

readonly permissions: readonly ProfilePermission[];

Defined in: packages/sage/src/internal/c4/identity.ts:44

permissionsRaw

readonly permissionsRaw: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:43

scope

readonly scope: Address;

Defined in: packages/sage/src/internal/c4/identity.ts:40

---

ProfileKeyInspection

Defined in: packages/sage/src/identity/permissions.ts:194

Immutable diagnostics for one original Profile key, never a selected authority. A match is advisory, not chain authorization; unknown requirements are indeterminate.

Example

declare const candidate: ProfileKeyInspection;
console.log(candidate.keyIndex, candidate.status, candidate.diagnostics);

Properties

address

readonly address: Address;

Defined in: packages/sage/src/identity/permissions.ts:196

diagnostics

readonly diagnostics: readonly ProfileKeyDiagnostic[];

Defined in: packages/sage/src/identity/permissions.ts:203

expired

readonly expired: boolean;

Defined in: packages/sage/src/identity/permissions.ts:202

expiresAt?

readonly optional expiresAt?: bigint;

Defined in: packages/sage/src/identity/permissions.ts:201

expiresAtRaw

readonly expiresAtRaw: bigint;

Defined in: packages/sage/src/identity/permissions.ts:200

isProfileAuthority

readonly isProfileAuthority: boolean;

Defined in: packages/sage/src/identity/permissions.ts:199

keyIndex

readonly keyIndex: number;

Defined in: packages/sage/src/identity/permissions.ts:195

permissionsRaw

readonly permissionsRaw: bigint;

Defined in: packages/sage/src/identity/permissions.ts:198

scope

readonly scope: Address;

Defined in: packages/sage/src/identity/permissions.ts:197

status

readonly status: "match" | "mismatch" | "indeterminate";

Defined in: packages/sage/src/identity/permissions.ts:204

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/permissions.ts:205

Returns

unknown

---

ProfileKeyRequirement

Defined in: packages/sage/src/identity/permissions.ts:168

Explicit direct-key requirement evaluated only at the caller’s supplied time.

Example

declare const signer: Address;
const requirement: ProfileKeyRequirement = {signer, scope: PROFILE_PERMISSION_SCOPE, permissionsRaw: 4n, at: 100n};

Properties

at

readonly at: bigint;

Defined in: packages/sage/src/identity/permissions.ts:172

permissionsRaw

readonly permissionsRaw: bigint;

Defined in: packages/sage/src/identity/permissions.ts:171

scope

readonly scope: Address;

Defined in: packages/sage/src/identity/permissions.ts:170

signer

readonly signer: Address;

Defined in: packages/sage/src/identity/permissions.ts:169

---

ProfilePermissionInspection

Defined in: packages/sage/src/identity/permissions.ts:129

Immutable scoped permission meanings with all raw bits retained.

Example

const inspection: ProfilePermissionInspection = inspectProfilePermissions(PROFILE_PERMISSION_SCOPE, 1n);

Properties

permissions

readonly permissions: readonly ProfilePermission[];

Defined in: packages/sage/src/identity/permissions.ts:132

permissionsRaw

readonly permissionsRaw: bigint;

Defined in: packages/sage/src/identity/permissions.ts:131

scope

readonly scope: Address;

Defined in: packages/sage/src/identity/permissions.ts:130

unrecognizedBitsRaw

readonly unrecognizedBitsRaw: bigint;

Defined in: packages/sage/src/identity/permissions.ts:133

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/permissions.ts:134

Returns

unknown

---

ProfileSnapshot

Defined in: packages/sage/src/identity/index.ts:107

Immutable, translated Player Profile snapshot.

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const profile: ProfileSnapshot = await getProfile(ctx, profileAddress);
console.log(profile.address, profile.keys.length);

Extends

• ProfileAccountData

Extended by

• ProfileView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/identity/index.ts:109

authKeyCount

readonly authKeyCount: number;

Defined in: packages/sage/src/internal/c4/identity.ts:56

Inherited from

ProfileAccountData.authKeyCount

createdAt

readonly createdAt: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:59

Inherited from

ProfileAccountData.createdAt

keys

readonly keys: readonly ProfileKeyData[];

Defined in: packages/sage/src/internal/c4/identity.ts:60

Inherited from

ProfileAccountData.keys

keyThreshold

readonly keyThreshold: number;

Defined in: packages/sage/src/internal/c4/identity.ts:57

Inherited from

ProfileAccountData.keyThreshold

kind

readonly kind: "profile";

Defined in: packages/sage/src/identity/index.ts:108

nextSeqId

readonly nextSeqId: bigint;

Defined in: packages/sage/src/internal/c4/identity.ts:58

Inherited from

ProfileAccountData.nextSeqId

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/identity.ts:55

Inherited from

ProfileAccountData.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/index.ts:110

Returns

unknown

---

RareMineralDiscoveryData

Defined in: packages/sage/src/internal/c4/character.ts:84

One translated cargo-specific research modifier.

Example

declare const discovery: RareMineralDiscoveryData;
const multiplier = discovery.multiplier;

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/internal/c4/character.ts:85

multiplier

readonly multiplier: number;

Defined in: packages/sage/src/internal/c4/character.ts:86

multiplierRaw

readonly multiplierRaw: bigint;

Defined in: packages/sage/src/internal/c4/character.ts:87

---

ResearchCatalogSnapshot

Defined in: packages/sage/src/identity/index.ts:162

Independent Game research catalog without Character perk or unlock claims.

Example

declare const ctx: SageContext;
const catalog: ResearchCatalogSnapshot = await getResearchCatalog(ctx);
console.log(catalog.nodes.length);

Properties

game

readonly game: EntityRef<"game">;

Defined in: packages/sage/src/identity/index.ts:164

kind

readonly kind: "researchCatalog";

Defined in: packages/sage/src/identity/index.ts:163

nodes

readonly nodes: readonly GameResearchNodeData[];

Defined in: packages/sage/src/identity/index.ts:165

sequenceId

readonly sequenceId: number;

Defined in: packages/sage/src/identity/index.ts:166

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/identity/index.ts:167

Returns

unknown

Type Aliases

ProfileKeyDiagnostic

type ProfileKeyDiagnostic =
  | "address-mismatch"
  | "scope-mismatch"
  | "expired"
  | "missing-permissions"
  | "unrecognized-permissions";

Defined in: packages/sage/src/identity/permissions.ts:180

Reasons an inspected entry does not prove a direct scoped snapshot match.

Example

const diagnostic: ProfileKeyDiagnostic = 'scope-mismatch';

---

ProfilePermission

type ProfilePermission =
  | "authenticate"
  | "addKeys"
  | "removeKeys"
  | "changeName"
  | "createRole"
  | "removeRole"
  | "setAuthorizer"
  | "joinRole"
  | "leaveRole"
  | "toggleAcceptingNewMembers"
  | "addMember"
  | "removeMember"
  | "drainSolVault"
  | "manageGame"
  | "manageSystem"
  | "manageStar"
  | "managePlanet"
  | "manageShip"
  | "manageCharacter"
  | "manageStarbase"
  | "manageMineItem"
  | "manageResource"
  | "removeShipEscrow"
  | "moveFleet"
  | "undock"
  | "dock"
  | "rentFleet"
  | "doCrafting"
  | "manageCargoPod"
  | "addRemoveCargo"
  | "doStarbaseUpgrades"
  | "manageFleet"
  | "manageFleetCargo"
  | "doMining"
  | "respawn"
  | "manageSurveyDataUnit"
  | "scanSurveyDataUnit"
  | "doStarbaseUpkeep"
  | "manageProgression"
  | "manageCrewConfig"
  | "manageCrew"
  | "withdrawCrew"
  | "manageRegion"
  | "manageCargo"
  | "manageClaimStakeConfig"
  | "manageCombat"
  | "manageClaimStake"
  | "manageCrafting"
  | "engageInCombat"
  | "repair"
  | "manageScanning"
  | "scan"
  | "manageLocalMarketOrders"
  | "doResearch"
  | "dailyCheckIn"
  | "manageCurrency"
  | "manageMissions"
  | "doGovernance"
  | "manageMissionTreasuries";

Defined in: packages/sage/src/internal/c4/profile-permissions.ts:16

Stable labels for recognized scoped permissions carried by Profile keys. Profile and SAGE meanings require their exact supported program scope.

Example

const permission: ProfilePermission = 'authenticate';

---

ResearchNodeDefinition

type ResearchNodeDefinition = GameResearchNodeData;

Defined in: packages/sage/src/identity/index.ts:95

One Game research node definition with no claimed player unlock state.

Example

declare const node: ResearchNodeDefinition;
console.log(node.name, node.maxLevel);

---

RiskZoneAccess

type RiskZoneAccess = "low" | "medium" | "high";

Defined in: packages/sage/src/internal/c4/character.ts:75

Stable risk-zone labels translated from generated numeric enums.

Example

const access: RiskZoneAccess = 'low';

---

ShipSize

type ShipSize =
  | "xx-small"
  | "x-small"
  | "small"
  | "medium"
  | "large"
  | "capital"
  | "commander"
  | "titan";

Defined in: packages/sage/src/internal/c4/character.ts:59

Stable ship-size labels translated from generated numeric enums.

Example

const size: ShipSize = 'medium';

---

WalletProfileDiscoveryOptions

type WalletProfileDiscoveryOptions =
  | Omit<ReadOptions, "maxAgeMs" | "refresh"> & {
  addresses: readonly Address[];
  strategy: "known-addresses";
}
  | Omit<ReadOptions, "maxAgeMs" | "refresh"> & {
  addresses?: never;
  strategy: "provider";
};

Defined in: packages/sage/src/identity/index.ts:185

Explicit strategy and read controls for wallet-to-Profile discovery.

Known addresses and provider hints follow the same direct on-chain validation path. The strategy is required so callers never mistake a known application mapping for provider discovery.

Example

declare const profileAddress: Address;
const options: WalletProfileDiscoveryOptions = {
  strategy: 'known-addresses',
  addresses: [profileAddress],
};

---

XpCategory

type XpCategory = GameXpCategory;

Defined in: packages/sage/src/identity/index.ts:68

Stable gameplay label for one Game XP category.

Example

const category: XpCategory = 'pilot';

---

XpDefinitions

type XpDefinitions = GameXpDefinitionsSectionData;

Defined in: packages/sage/src/identity/index.ts:86

Sequence-versioned Game XP rules joined to Character XP.

Example

declare const definitions: XpDefinitions;
console.log(definitions.sequenceId);

---

XpLevelThreshold

type XpLevelThreshold = GameXpLevelThresholdData;

Defined in: packages/sage/src/identity/index.ts:77

Exact XP thresholds for one level across every category.

Example

declare const threshold: XpLevelThreshold;
console.log(threshold.pilot);

Variables

PROFILE_PERMISSION_SCOPE

const PROFILE_PERMISSION_SCOPE: Address = PROFILE_SCOPE;

Defined in: packages/sage/src/identity/permissions.ts:19

Pinned supported Player Profile program scope, where bit zero means AUTH.

Example

const mask = composeProfilePermissions(PROFILE_PERMISSION_SCOPE, ['authenticate']);

---

SAGE_PERMISSION_SCOPE

const SAGE_PERMISSION_SCOPE: Address = SAGE_SCOPE;

Defined in: packages/sage/src/identity/permissions.ts:28

Pinned supported SAGE program scope, where bit zero means manageGame. Recognized names describe bits, not complete action authorization policies.

Example

const mask = composeProfilePermissions(SAGE_PERMISSION_SCOPE, ['moveFleet']);

Functions

composeProfilePermissions()

function composeProfilePermissions(scope, names): bigint;

Defined in: packages/sage/src/identity/permissions.ts:67

Compose only verified names under an explicit scope. Empty input returns zero. Profile and SAGE names require their exact supported program scope; drainSolVault is recognized across scopes. Names identify verified bits, not complete action authorization policies. No default authority mask is added.

Parameters

Parameter	Type
scope	Address
names	readonly ProfilePermission[]

Returns

bigint

Example

const raw = composeProfilePermissions(PROFILE_PERMISSION_SCOPE, ['addKeys', 'removeKeys']);

---

containsProfilePermissions()

function containsProfilePermissions(availableRaw, requiredRaw): boolean;

Defined in: packages/sage/src/identity/permissions.ts:115

Numeric bit containment only, including unknown bits; this is not authorization. Callers must track the scope each mask belongs to; this pure bit operation neither checks scope compatibility nor interprets permission meanings.

Parameters

Parameter	Type
availableRaw	bigint
requiredRaw	bigint

Returns

boolean

Example

const contains = containsProfilePermissions(6n, 4n);

---

deriveCharacterResearchState()

function deriveCharacterResearchState(character): CharacterResearchState;

Defined in: packages/sage/src/identity/research-state.ts:79

Projects stored XP, career research points, Renown and acquired nodes without I/O, mutation, or a separate cache. Career points use level minus spent; Renown uses earned minus spent. Daily XP is not a career and is excluded. Balances clamp at zero; bigint values serialize as decimal strings.

Input must be an SDK-loaded Character. The result reflects that read’s state, not necessarily current Game rules: compare researchSequenceId with the catalog sequence and require pendingNodeUpdates === 0 before treating perks as synchronized. Use getCharacterProgressionForProfile for the optional sequence-matched XP-definition join. This helper does not authorize research.

Parameters

Parameter	Type
character	Pick<CharacterSnapshot, "address" | "xp" | "modifiers">

Returns

CharacterResearchState

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const character = await getCharacterForProfile(ctx, profileAddress);
const state = deriveCharacterResearchState(character);
console.log(state.careers.pilot.earnedXp, state.careers.pilot.level);
console.log(state.renown.available, state.nodes);

---

getCharacterForProfile()

function getCharacterForProfile(
   ctx,
   profileAddress,
options?): Promise<CharacterSnapshot>;

Defined in: packages/sage/src/identity/index.ts:452

Derives and reads the Character associated with a known Player Profile.

Parameters

Parameter	Type
ctx	SageContext
profileAddress	Address
options?	ReadOptions

Returns

Promise<CharacterSnapshot>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const character = await getCharacterForProfile(ctx, profileAddress);

---

getCharacterProgressionForProfile()

function getCharacterProgressionForProfile(
   ctx,
   profileAddress,
options?): Promise<CharacterProgressionSnapshot>;

Defined in: packages/sage/src/identity/index.ts:371

Reads a derived Character and joins its XP state to matching Game rules.

The Profile-to-Character PDA remains the canonical discovery path. Game XP rules are loaded lazily and must carry the Character’s exact sequence id.

Parameters

Parameter	Type
ctx	SageContext
profileAddress	Address
options?	ReadOptions

Returns

Promise<CharacterProgressionSnapshot>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const progression = await getCharacterProgressionForProfile(ctx, profileAddress);

---

getCharactersForWallet()

function getCharactersForWallet(
   ctx,
   wallet,
options): Promise<readonly CharacterSnapshot[]>;

Defined in: packages/sage/src/identity/index.ts:639

Resolves wallet Profiles and derives every Character currently present for them.

The returned list preserves the wallet discovery strategy metadata. Profiles without a Character are omitted because Character creation is optional.

Parameters

Parameter	Type
ctx	SageContext
wallet	Address
options	WalletProfileDiscoveryOptions

Returns

Promise<readonly CharacterSnapshot[]>

Example

declare const ctx: SageContext;
declare const wallet: Address;
const characters = await getCharactersForWallet(ctx, wallet, {
  strategy: 'provider',
});

---

getProfile()

function getProfile(
   ctx,
   address,
options?): Promise<ProfileSnapshot>;

Defined in: packages/sage/src/identity/index.ts:349

Reads a required Player Profile by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<ProfileSnapshot>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const profile = await getProfile(ctx, profileAddress);

---

getProfilesForWallet()

function getProfilesForWallet(
   ctx,
   wallet,
options): Promise<readonly ProfileSnapshot[]>;

Defined in: packages/sage/src/identity/index.ts:511

Resolves and directly validates zero, one, or many Player Profiles for a wallet.

Provider and known-address results are address hints only. Every unique candidate is read through the context data plane, validated as a Player Profile, and checked for the requested wallet in its decoded key list. Stored matching keys are accepted regardless of expiry; consumers remain responsible for applying authorization policy to the returned key details. Missing candidates are treated as stale hints and omitted; a contradictory present Profile rejects the discovery.

Parameters

Parameter	Type
ctx	SageContext
wallet	Address
options	WalletProfileDiscoveryOptions

Returns

Promise<readonly ProfileSnapshot[]>

Example

declare const ctx: SageContext;
declare const wallet: Address;
const profiles = await getProfilesForWallet(ctx, wallet, {
  strategy: 'provider',
});

---

getResearchCatalog()

function getResearchCatalog(ctx): Promise<ResearchCatalogSnapshot>;

Defined in: packages/sage/src/identity/index.ts:395

Reads the Game research tree as an independent, context-cached catalog.

The result intentionally has no Character relation, unlock flags, perk state, or inferred player ownership. It also has no read metadata because the definitions registry does not expose an authoritative per-read envelope.

Parameters

Parameter	Type
ctx	SageContext

Returns

Promise<ResearchCatalogSnapshot>

Example

declare const ctx: SageContext;
const catalog = await getResearchCatalog(ctx);

---

inspectProfileKeys()

function inspectProfileKeys(profile, requirement): readonly ProfileKeyInspection[];

Defined in: packages/sage/src/identity/permissions.ts:221

Inspect every key against an exact scope, mask, direct signer and explicit time. No AUTH override, role/certificate delegation, threshold policy, RPC, wall clock, refresh or signer is used. All original indices remain visible; select an index explicitly for an existing planner and retain its freshness and simulation checks. Canonical expiresAtRaw controls expiry; negative values are permanent. A key remains unexpired at its exact expiry second and expires only when at is later.

Parameters

Parameter	Type
profile	ProfileSnapshot
requirement	ProfileKeyRequirement

Returns

readonly ProfileKeyInspection[]

Example

declare const profile: ProfileSnapshot;
declare const requirement: ProfileKeyRequirement;
const candidates = inspectProfileKeys(profile, requirement);
console.log(candidates.map(key => [key.keyIndex, key.status]));

---

inspectProfilePermissions()

function inspectProfilePermissions(scope, permissionsRaw): ProfilePermissionInspection;

Defined in: packages/sage/src/identity/permissions.ts:143

Inspect known meanings without discarding unrecognized raw bits.

Parameters

Parameter	Type
scope	Address
permissionsRaw	bigint

Returns

ProfilePermissionInspection

Example

const inspection = inspectProfilePermissions(PROFILE_PERMISSION_SCOPE, 1n);
console.log(inspection.permissions, inspection.unrecognizedBitsRaw);

---

maybeGetCharacterForProfile()

function maybeGetCharacterForProfile(
   ctx,
   profileAddress,
   options?): Promise<
  | CharacterSnapshot
| undefined>;

Defined in: packages/sage/src/identity/index.ts:475

Derives and optionally reads the Character for a known Player Profile.

Parameters

Parameter	Type
ctx	SageContext
profileAddress	Address
options?	ReadOptions

Returns

Promise< | CharacterSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const character = await maybeGetCharacterForProfile(ctx, profileAddress);

---

maybeGetProfile()

function maybeGetProfile(
   ctx,
   address,
options?): Promise<ProfileSnapshot | undefined>;

Defined in: packages/sage/src/identity/index.ts:430

Reads an optional Player Profile by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<ProfileSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const profile = await maybeGetProfile(ctx, profileAddress);

---

unionProfilePermissionMasks()

function unionProfilePermissionMasks(masks): bigint;

Defined in: packages/sage/src/identity/permissions.ts:99

Union exact raw masks, preserving unknown bits. Empty input returns zero. This is a pure bit operation. Callers must track the scope each mask belongs to; combining masks does not establish permission meanings or authorization.

Parameters

Parameter	Type
masks	readonly bigint[]

Returns

bigint

Example

const raw = unionProfilePermissionMasks([4n, 0n]);