loyalty

Interfaces

LoyaltyAtlasBankSnapshot

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

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

bump

readonly bump: number;

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

Inherited from

Omit.bump

claimableAtlasRaw

readonly claimableAtlasRaw: bigint;

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

Inherited from

Omit.claimableAtlasRaw

expiresAtUnixSeconds

readonly expiresAtUnixSeconds: bigint;

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

Inherited from

Omit.expiresAtUnixSeconds

faction

readonly faction: EntityRef<"faction">;

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

factionId

readonly factionId: number;

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

game

readonly game: EntityRef<"game">;

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

kind

readonly kind: "loyaltyAtlasBank";

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

lastCreditedAtUnixSeconds

readonly lastCreditedAtUnixSeconds: bigint;

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

Inherited from

Omit.lastCreditedAtUnixSeconds

lifetimeAtlasRaw

readonly lifetimeAtlasRaw: bigint;

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

Inherited from

Omit.lifetimeAtlasRaw

lifetimeLpRaw

readonly lifetimeLpRaw: bigint;

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

Inherited from

Omit.lifetimeLpRaw

profile

readonly profile: EntityRef<"profile">;

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

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

---

LoyaltyContributionSnapshot

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

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

atlasEntitlementRaw

readonly atlasEntitlementRaw: bigint;

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

Inherited from

Omit.atlasEntitlementRaw

bump

readonly bump: number;

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

Inherited from

Omit.bump

epoch

readonly epoch: EntityRef<"loyaltyEpoch">;

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

epochIndex

readonly epochIndex: bigint;

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

Inherited from

Omit.epochIndex

faction

readonly faction: EntityRef<"faction">;

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

factionId

readonly factionId: number;

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

game

readonly game: EntityRef<"game">;

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

kind

readonly kind: "loyaltyContribution";

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

lpRaw

readonly lpRaw: bigint;

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

Inherited from

Omit.lpRaw

profile

readonly profile: EntityRef<"profile">;

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

settled

readonly settled: boolean;

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

Inherited from

Omit.settled

settledAtUnixSeconds

readonly settledAtUnixSeconds: bigint | undefined;

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

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

---

LoyaltyEpochSnapshot

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

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

bump

readonly bump: number;

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

Inherited from

Omit.bump

configVersion

readonly configVersion: number;

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

Inherited from

Omit.configVersion

endsAtUnixSeconds

readonly endsAtUnixSeconds: bigint;

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

Inherited from

Omit.endsAtUnixSeconds

epochIndex

readonly epochIndex: bigint;

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

Inherited from

Omit.epochIndex

faction

readonly faction: EntityRef<"faction">;

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

factionId

readonly factionId: number;

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

game

readonly game: EntityRef<"game">;

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

kind

readonly kind: "loyaltyEpoch";

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

kingSystems

readonly kingSystems: number;

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

Inherited from

Omit.kingSystems

poolAtlasRaw

readonly poolAtlasRaw: bigint;

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

Inherited from

Omit.poolAtlasRaw

rewardConfig

readonly rewardConfig: EntityRef<"atlasRewardConfig">;

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

settledAtlasRaw

readonly settledAtlasRaw: bigint;

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

Inherited from

Omit.settledAtlasRaw

settlementDeadlineUnixSeconds

readonly settlementDeadlineUnixSeconds: bigint;

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

Inherited from

Omit.settlementDeadlineUnixSeconds

startsAtUnixSeconds

readonly startsAtUnixSeconds: bigint;

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

Inherited from

Omit.startsAtUnixSeconds

status

readonly status: LoyaltyEpochStatus;

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

Inherited from

Omit.status

totalLpRaw

readonly totalLpRaw: bigint;

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

Inherited from

Omit.totalLpRaw

unsettledAtlasRaw

readonly unsettledAtlasRaw: bigint;

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

Inherited from

Omit.unsettledAtlasRaw

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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);