loyalty

Interfaces

LoyaltyAtlasBankSnapshot

Defined in: packages/sage/src/loyalty/index.ts:93

Immutable accumulated ATLAS bank for one Profile and faction.

Example

declare const bank: LoyaltyAtlasBankSnapshot;
console.log(bank.claimableAtlasRaw, bank.expiresAtUnixSeconds);

Extends

• Omit<LoyaltyAtlasBankAccountData, "game" | "profile" | "factionId">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/loyalty/index.ts:98

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/loyalty.ts:138

Inherited from

Omit.bump

claimableAtlasRaw

readonly claimableAtlasRaw: bigint;

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

Inherited from

Omit.claimableAtlasRaw

expiresAtUnixSeconds

readonly expiresAtUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/loyalty.ts:146

Inherited from

Omit.expiresAtUnixSeconds

faction

readonly faction: EntityRef<"faction">;

Defined in: packages/sage/src/loyalty/index.ts:102

factionId

readonly factionId: number;

Defined in: packages/sage/src/loyalty/index.ts:101

game

readonly game: EntityRef<"game">;

Defined in: packages/sage/src/loyalty/index.ts:99

kind

readonly kind: "loyaltyAtlasBank";

Defined in: packages/sage/src/loyalty/index.ts:97

lastCreditedAtUnixSeconds

readonly lastCreditedAtUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/loyalty.ts:145

Inherited from

Omit.lastCreditedAtUnixSeconds

lifetimeAtlasRaw

readonly lifetimeAtlasRaw: bigint;

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

Inherited from

Omit.lifetimeAtlasRaw

lifetimeLpRaw

readonly lifetimeLpRaw: bigint;

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

Inherited from

Omit.lifetimeLpRaw

profile

readonly profile: EntityRef<"profile">;

Defined in: packages/sage/src/loyalty/index.ts:100

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/loyalty.ts:137

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/loyalty/index.ts:103

Returns

unknown

---

LoyaltyContributionSnapshot

Defined in: packages/sage/src/loyalty/index.ts:71

Immutable Profile contribution for one faction epoch.

Example

declare const contribution: LoyaltyContributionSnapshot;
console.log(contribution.profile.address, contribution.lpRaw);

Extends

• Omit<LoyaltyContributionAccountData, "game" | "profile" | "factionId" | "settledAtUnixSeconds">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/loyalty/index.ts:76

atlasEntitlementRaw

readonly atlasEntitlementRaw: bigint;

Defined in: packages/sage/src/internal/c4/loyalty.ts:132

Inherited from

Omit.atlasEntitlementRaw

bump

readonly bump: number;

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

Inherited from

Omit.bump

epoch

readonly epoch: EntityRef<"loyaltyEpoch">;

Defined in: packages/sage/src/loyalty/index.ts:81

epochIndex

readonly epochIndex: bigint;

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

Inherited from

Omit.epochIndex

faction

readonly faction: EntityRef<"faction">;

Defined in: packages/sage/src/loyalty/index.ts:80

factionId

readonly factionId: number;

Defined in: packages/sage/src/loyalty/index.ts:79

game

readonly game: EntityRef<"game">;

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

kind

readonly kind: "loyaltyContribution";

Defined in: packages/sage/src/loyalty/index.ts:75

lpRaw

readonly lpRaw: bigint;

Defined in: packages/sage/src/internal/c4/loyalty.ts:131

Inherited from

Omit.lpRaw

profile

readonly profile: EntityRef<"profile">;

Defined in: packages/sage/src/loyalty/index.ts:78

settled

readonly settled: boolean;

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

Inherited from

Omit.settled

settledAtUnixSeconds

readonly settledAtUnixSeconds: bigint | undefined;

Defined in: packages/sage/src/loyalty/index.ts:82

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/loyalty/index.ts:83

Returns

unknown

---

LoyaltyEpochSnapshot

Defined in: packages/sage/src/loyalty/index.ts:51

Immutable faction loyalty epoch with exact LP/ATLAS values.

Example

declare const epoch: LoyaltyEpochSnapshot;
console.log(epoch.faction.address, epoch.totalLpRaw);

Extends

• Omit<LoyaltyEpochAccountData, "game" | "factionId">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/loyalty/index.ts:56

bump

readonly bump: number;

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

Inherited from

Omit.bump

configVersion

readonly configVersion: number;

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

Inherited from

Omit.configVersion

endsAtUnixSeconds

readonly endsAtUnixSeconds: bigint;

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

Inherited from

Omit.endsAtUnixSeconds

epochIndex

readonly epochIndex: bigint;

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

Inherited from

Omit.epochIndex

faction

readonly faction: EntityRef<"faction">;

Defined in: packages/sage/src/loyalty/index.ts:59

factionId

readonly factionId: number;

Defined in: packages/sage/src/loyalty/index.ts:58

game

readonly game: EntityRef<"game">;

Defined in: packages/sage/src/loyalty/index.ts:57

kind

readonly kind: "loyaltyEpoch";

Defined in: packages/sage/src/loyalty/index.ts:55

kingSystems

readonly kingSystems: number;

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

Inherited from

Omit.kingSystems

poolAtlasRaw

readonly poolAtlasRaw: bigint;

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

Inherited from

Omit.poolAtlasRaw

rewardConfig

readonly rewardConfig: EntityRef<"atlasRewardConfig">;

Defined in: packages/sage/src/loyalty/index.ts:60

settledAtlasRaw

readonly settledAtlasRaw: bigint;

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

Inherited from

Omit.settledAtlasRaw

settlementDeadlineUnixSeconds

readonly settlementDeadlineUnixSeconds: bigint;

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

Inherited from

Omit.settlementDeadlineUnixSeconds

startsAtUnixSeconds

readonly startsAtUnixSeconds: bigint;

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

Inherited from

Omit.startsAtUnixSeconds

status

readonly status: LoyaltyEpochStatus;

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

Inherited from

Omit.status

totalLpRaw

readonly totalLpRaw: bigint;

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

Inherited from

Omit.totalLpRaw

unsettledAtlasRaw

readonly unsettledAtlasRaw: bigint;

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

Inherited from

Omit.unsettledAtlasRaw

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/loyalty/index.ts:61

Returns

unknown

Type Aliases

LoyaltyAtlasBankState

type LoyaltyAtlasBankState =
  | {
  kind: "empty";
}
  | {
  claimableAtlasRaw: bigint;
  kind: "claimable";
}
  | {
  claimableAtlasRaw: bigint;
  kind: "expired";
};

Defined in: packages/sage/src/loyalty/index.ts:136

Claimability state of one loyalty ATLAS bank.

Example

const state: LoyaltyAtlasBankState = { kind: 'empty' };

---

LoyaltyContributionState

type LoyaltyContributionState =
  | {
  kind: "unsettled";
}
  | {
  kind: "settled";
  settledAtUnixSeconds: bigint;
}
  | {
  kind: "expired";
};

Defined in: packages/sage/src/loyalty/index.ts:125

Settlement state of one loyalty contribution.

Example

const state: LoyaltyContributionState = { kind: 'unsettled' };

---

LoyaltyDiscoveryOptions

type LoyaltyDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy">;

Defined in: packages/sage/src/loyalty/index.ts:39

Options accepted by targeted loyalty reverse discovery.

Example

const options: LoyaltyDiscoveryOptions = { commitment: 'confirmed' };

---

LoyaltyEpochState

type LoyaltyEpochState =
  | {
  kind: "scheduled";
}
  | {
  kind: "open";
  remainingSeconds: bigint;
}
  | {
  kind: "settling";
  remainingSeconds: bigint;
}
  | {
  kind: "expired";
}
  | {
  kind: "swept";
};

Defined in: packages/sage/src/loyalty/index.ts:112

Time-projected lifecycle of one loyalty epoch.

Example

const state: LoyaltyEpochState = { kind: 'scheduled' };

Functions

deriveLoyaltyAtlasBankState()

function deriveLoyaltyAtlasBankState(bank, atUnixSeconds): LoyaltyAtlasBankState;

Defined in: packages/sage/src/loyalty/index.ts:641

Projects whether an accumulated ATLAS bank is empty, claimable, or expired.

Parameters

Parameter	Type
bank	Pick<LoyaltyAtlasBankSnapshot, "claimableAtlasRaw" | "expiresAtUnixSeconds">
atUnixSeconds	bigint

Returns

LoyaltyAtlasBankState

Example

declare const bank: LoyaltyAtlasBankSnapshot;
const state = deriveLoyaltyAtlasBankState(bank, 1_700_000_000n);

---

deriveLoyaltyContributionState()

function deriveLoyaltyContributionState(
   contribution,
   epoch,
   atUnixSeconds): LoyaltyContributionState;

Defined in: packages/sage/src/loyalty/index.ts:588

Projects settlement or expiry for one contribution and matching epoch. Unsettled contributions are expired as soon as their epoch is swept.

Parameters

Parameter	Type
contribution	Pick<LoyaltyContributionSnapshot, "settled" | "settledAtUnixSeconds" | "epoch" | "factionId" | "game">
epoch	Pick<LoyaltyEpochSnapshot, | "address" | "factionId" | "game" | "status" | "endsAtUnixSeconds" | "settlementDeadlineUnixSeconds">
atUnixSeconds	bigint

Returns

LoyaltyContributionState

Example

declare const contribution: LoyaltyContributionSnapshot;
declare const epoch: LoyaltyEpochSnapshot;
const state = deriveLoyaltyContributionState(contribution, epoch, 1_700_000_000n);

---

deriveLoyaltyEpochState()

function deriveLoyaltyEpochState(epoch, atUnixSeconds): LoyaltyEpochState;

Defined in: packages/sage/src/loyalty/index.ts:548

Projects a loyalty epoch at an explicit Unix timestamp.

Parameters

Parameter	Type
epoch	Pick<LoyaltyEpochSnapshot, | "status" | "startsAtUnixSeconds" | "endsAtUnixSeconds" | "settlementDeadlineUnixSeconds">
atUnixSeconds	bigint

Returns

LoyaltyEpochState

Example

declare const epoch: LoyaltyEpochSnapshot;
const state = deriveLoyaltyEpochState(epoch, epoch.startsAtUnixSeconds);

---

getLoyaltyAtlasBank()

function getLoyaltyAtlasBank(
   context,
   profile,
   factionId,
options?): Promise<LoyaltyAtlasBankSnapshot>;

Defined in: packages/sage/src/loyalty/index.ts:437

Derives and reads a required Profile loyalty ATLAS bank.

Parameters

Parameter	Type
context	SageContext
profile	Address
factionId	number
options?	ReadOptions

Returns

Promise<LoyaltyAtlasBankSnapshot>

Example

declare const ctx: SageContext;
declare const profile: Address;
const bank = await getLoyaltyAtlasBank(ctx, profile, 3);

---

getLoyaltyAtlasBanksByProfile()

function getLoyaltyAtlasBanksByProfile(
   context,
   profile,
options?): Promise<readonly LoyaltyAtlasBankSnapshot[]>;

Defined in: packages/sage/src/loyalty/index.ts:523

Discovers validated loyalty ATLAS banks for one Profile.

Parameters

Parameter	Type
context	SageContext
profile	Address
options?	LoyaltyDiscoveryOptions

Returns

Promise<readonly LoyaltyAtlasBankSnapshot[]>

Example

declare const ctx: SageContext;
declare const profile: Address;
const banks = await getLoyaltyAtlasBanksByProfile(ctx, profile);

---

getLoyaltyContribution()

function getLoyaltyContribution(
   context,
   profile,
   factionId,
   epochIndex,
options?): Promise<LoyaltyContributionSnapshot>;

Defined in: packages/sage/src/loyalty/index.ts:343

Derives and reads one required Profile contribution.

Parameters

Parameter	Type
context	SageContext
profile	Address
factionId	number
epochIndex	bigint
options?	ReadOptions

Returns

Promise<LoyaltyContributionSnapshot>

Example

declare const ctx: SageContext;
declare const profile: Address;
const contribution = await getLoyaltyContribution(ctx, profile, 1, 20_668n);

---

getLoyaltyContributionsByProfile()

function getLoyaltyContributionsByProfile(
   context,
   profile,
options?): Promise<readonly LoyaltyContributionSnapshot[]>;

Defined in: packages/sage/src/loyalty/index.ts:497

Discovers validated loyalty contributions for one Profile.

Parameters

Parameter	Type
context	SageContext
profile	Address
options?	LoyaltyDiscoveryOptions

Returns

Promise<readonly LoyaltyContributionSnapshot[]>

Example

declare const ctx: SageContext;
declare const profile: Address;
const contributions = await getLoyaltyContributionsByProfile(ctx, profile);

---

getLoyaltyEpoch()

function getLoyaltyEpoch(
   context,
   factionId,
   epochIndex,
options?): Promise<LoyaltyEpochSnapshot>;

Defined in: packages/sage/src/loyalty/index.ts:318

Derives and reads one required faction loyalty epoch.

Parameters

Parameter	Type
context	SageContext
factionId	number
epochIndex	bigint
options?	ReadOptions

Returns

Promise<LoyaltyEpochSnapshot>

Example

declare const ctx: SageContext;
const epoch = await getLoyaltyEpoch(ctx, 1, 20_665n);

---

getLoyaltyEpochsByFaction()

function getLoyaltyEpochsByFaction(
   context,
   factionId,
options?): Promise<readonly LoyaltyEpochSnapshot[]>;

Defined in: packages/sage/src/loyalty/index.ts:471

Discovers validated loyalty epochs for one faction.

Parameters

Parameter	Type
context	SageContext
factionId	number
options?	LoyaltyDiscoveryOptions

Returns

Promise<readonly LoyaltyEpochSnapshot[]>

Example

declare const ctx: SageContext;
const epochs = await getLoyaltyEpochsByFaction(ctx, 1);

---

maybeGetLoyaltyAtlasBank()

function maybeGetLoyaltyAtlasBank(
   context,
   profile,
   factionId,
   options?): Promise<
  | LoyaltyAtlasBankSnapshot
| undefined>;

Defined in: packages/sage/src/loyalty/index.ts:412

Derives and reads an optional Profile loyalty ATLAS bank.

Parameters

Parameter	Type
context	SageContext
profile	Address
factionId	number
options?	ReadOptions

Returns

Promise< | LoyaltyAtlasBankSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const profile: Address;
const bank = await maybeGetLoyaltyAtlasBank(ctx, profile, 3);