@aephia/atlas-kit 0.0.0

package/dist/internal/c4/rewards.js

@@ -0,0 +1,305 @@
+import { ATLAS_REWARD_CONFIG_DISCRIMINATOR, ATLAS_REWARD_REGISTRY_DISCRIMINATOR, ATLAS_REWARD_TREASURY_DISCRIMINATOR, LOOT_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, getAtlasRewardConfigDecoder, getAtlasRewardRegistryDecoder, getAtlasRewardTreasuryDecoder, getLootDecoder, } from '@staratlas/dev-sage';
+import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { AccountDecodeError, InvalidAccountOwnerError, InvalidDiscriminatorError, MissingGameContextError, } from '../../client/errors.js';
+import { deriveAtlasRewardConfigAddress } from './pda.js';
+import { assertLootLayout, LOOT_FILTER_OFFSETS, LOOT_MINIMUM_DATA_LENGTH, } from './loot-layout.js';
+const REGISTRY_DATA_LENGTH = 126;
+const CONFIG_DATA_LENGTH = 1_610;
+const TREASURY_MINIMUM_DATA_LENGTH = 46;
+const NO_PENDING_CONFIG_VERSION = 0xffff_ffff;
+const REGISTRY_DISCRIMINATOR = Object.freeze(Array.from(ATLAS_REWARD_REGISTRY_DISCRIMINATOR));
+const CONFIG_DISCRIMINATOR = Object.freeze(Array.from(ATLAS_REWARD_CONFIG_DISCRIMINATOR));
+const TREASURY_DISCRIMINATOR = Object.freeze(Array.from(ATLAS_REWARD_TREASURY_DISCRIMINATOR));
+const REWARD_LOOT_DISCRIMINATOR = Object.freeze(Array.from(LOOT_DISCRIMINATOR));
+export { LOOT_FILTER_OFFSETS as REWARD_LOOT_FILTER_OFFSETS } from './loot-layout.js';
+/** Audited read and deferred-action relationships for ATLAS rewards. */
+export const REWARD_RELATIONSHIPS = Object.freeze([
+    {
+        from: 'game | game + config version',
+        kind: 'derived',
+        mechanism: 'AtlasRewardRegistry, AtlasRewardConfig, and AtlasRewardTreasury PDA seeds',
+        to: 'reward registry | config | treasury',
+    },
+    {
+        from: 'registry | loot',
+        kind: 'stored',
+        mechanism: 'registry config/epoch selectors and Loot reward commitment fields',
+        to: 'config | epoch | reward commitment',
+    },
+    {
+        from: 'config | treasury | loot',
+        kind: 'nested',
+        mechanism: 'reward rates, curves, cargo reserves, and commitment legs',
+        to: 'reward values',
+    },
+    {
+        from: 'rewards',
+        kind: 'instruction-only',
+        mechanism: 'funding, advancement, settlement, and sweeping co-accounts are not durable relations',
+        to: 'actions',
+    },
+    {
+        from: 'profile',
+        kind: 'discovered',
+        mechanism: 'validated Loot discovery exposes only reward-bearing Loot references',
+        to: 'loot[]',
+    },
+]);
+function hasDiscriminator(data, discriminator) {
+    return discriminator.every((byte, index) => data[index] === byte);
+}
+function validate(account, type, discriminator, minimumLength, exact) {
+    if (account.owner !== SAGE_PROGRAM_ADDRESS) {
+        throw new InvalidAccountOwnerError(type, account.address, SAGE_PROGRAM_ADDRESS, account.owner);
+    }
+    if (account.data.length < discriminator.length ||
+        !hasDiscriminator(account.data, discriminator)) {
+        throw new InvalidDiscriminatorError(type, account.address);
+    }
+    if ((exact && account.data.length !== minimumLength) ||
+        (!exact && account.data.length < minimumLength)) {
+        throw new AccountDecodeError(type, account.address, new RangeError(`Expected ${exact ? 'exactly' : 'at least'} ${minimumLength} account bytes, received ${account.data.length}.`));
+    }
+}
+function decodeExactly(account, type, read) {
+    try {
+        const [decoded, offset] = read(account.data, 0);
+        if (offset !== account.data.length) {
+            throw new RangeError(`Decoded ${offset} of ${account.data.length} account bytes.`);
+        }
+        return decoded;
+    }
+    catch (cause) {
+        throw new AccountDecodeError(type, account.address, cause);
+    }
+}
+function translateRegistry(value) {
+    const noPending = value.pendingConfigVersion === NO_PENDING_CONFIG_VERSION;
+    if (noPending !== (value.pendingEffectiveEpoch === 0n)) {
+        throw new RangeError('AtlasRewardRegistry pending config sentinel is inconsistent.');
+    }
+    return {
+        activeConfigVersion: value.activeConfigVersion,
+        bump: value.bump,
+        currentEpoch: value.currentEpoch,
+        currentEpochEndsAtUnixSeconds: value.currentEpochEndsAt,
+        currentEpochStartedAtUnixSeconds: value.currentEpochStartedAt,
+        game: value.gameId,
+        initialEpochOffsetSeconds: value.initialEpochOffsetSecs,
+        latestConfigVersion: value.latestConfigVersion,
+        pendingConfig: noPending
+            ? { kind: 'none' }
+            : {
+                configVersion: value.pendingConfigVersion,
+                effectiveEpoch: value.pendingEffectiveEpoch,
+                kind: 'pending',
+            },
+        version: value.version,
+    };
+}
+function translateConfig(value) {
+    if (value.enabled !== 0 && value.enabled !== 1) {
+        throw new RangeError(`Unsupported AtlasRewardConfig enabled flag ${value.enabled}.`);
+    }
+    if (value.upgradeLpRateCount > value.upgradeLpRates.length ||
+        value.salvageEntryCount > value.salvageEntries.length) {
+        throw new RangeError('AtlasRewardConfig authored entry counts exceed fixed storage.');
+    }
+    return {
+        activeMedallion: {
+            buyerPriceAtlasRaw: value.activeMedallion.buyerPrice,
+            cargoId: value.activeMedallion.cargoId,
+            generation: value.activeMedallion.generation,
+        },
+        atlasBankInactivityExpirySeconds: value.atlasBankInactivityExpirySecs,
+        bump: value.bump,
+        claimSettlementWindowSeconds: value.claimSettlementWindowSecs,
+        configVersion: value.configVersion,
+        createdAtUnixSeconds: value.createdAt,
+        effectiveEpoch: value.effectiveEpoch,
+        enabled: value.enabled === 1,
+        epochLengthSeconds: value.epochLenSecs,
+        factionPoolLeverRaw: value.factionPoolLever,
+        game: value.gameId,
+        kingSystemCurveRaw: value.kingSystemCurve.map((row) => [...row]),
+        lossModelTargetBps: [...value.lossModelTargetBps],
+        medallionBuybackCapPerEpochRaw: value.medallionBuybackCapPerEpoch,
+        pveLpRateBps: value.pveLpRateBps,
+        pvpMedallionRateBps: value.pvpMedallionRateBps,
+        repairKitLpRateRaw: value.repairKitLpRate,
+        rewardLootReclaimSeconds: value.rewardLootReclaimSecs,
+        rewardReserveLowBalanceThresholdRaw: value.rewardReserveLowBalanceThreshold,
+        salvageEntries: value.salvageEntries
+            .slice(0, value.salvageEntryCount)
+            .map((entry) => ({
+            cargoId: entry.cargoId,
+            referenceValueAtlasRaw: entry.referenceValue,
+            weight: entry.weight,
+        })),
+        salvageEvRateBps: value.salvageEvRateBps,
+        sourceFlags: value.sourceFlags,
+        starbaseDestructionMedallionsRaw: [...value.starbaseDestructionMedallions],
+        upgradeLpRates: value.upgradeLpRates
+            .slice(0, value.upgradeLpRateCount)
+            .map((entry) => ({
+            cargoId: entry.cargoId,
+            lpPerRawUnit: entry.lpPerRawUnit,
+        })),
+        version: value.version,
+    };
+}
+function translateTreasury(value) {
+    return {
+        bump: value.bump,
+        game: value.gameId,
+        reserves: [...value.reserves].map(([cargoId, quantityRaw]) => ({
+            cargoId,
+            quantityRaw,
+        })),
+        version: value.version,
+    };
+}
+export const atlasRewardRegistryAccountDefinition = Object.freeze({
+    decode(account) {
+        validate(account, 'atlasRewardRegistry', REGISTRY_DISCRIMINATOR, REGISTRY_DATA_LENGTH, true);
+        const decoded = decodeExactly(account, 'atlasRewardRegistry', (bytes, offset) => getAtlasRewardRegistryDecoder().read(bytes, offset));
+        try {
+            return translateRegistry(decoded);
+        }
+        catch (cause) {
+            throw new AccountDecodeError('atlasRewardRegistry', account.address, cause);
+        }
+    },
+    discriminator: REGISTRY_DISCRIMINATOR,
+    minimumDataLength: REGISTRY_DATA_LENGTH,
+    programAddress: SAGE_PROGRAM_ADDRESS,
+    type: 'atlasRewardRegistry',
+    validate(account) {
+        validate(account, 'atlasRewardRegistry', REGISTRY_DISCRIMINATOR, REGISTRY_DATA_LENGTH, true);
+    },
+});
+export const atlasRewardConfigAccountDefinition = Object.freeze({
+    decode(account) {
+        validate(account, 'atlasRewardConfig', CONFIG_DISCRIMINATOR, CONFIG_DATA_LENGTH, true);
+        const decoded = decodeExactly(account, 'atlasRewardConfig', (bytes, offset) => getAtlasRewardConfigDecoder().read(bytes, offset));
+        try {
+            return translateConfig(decoded);
+        }
+        catch (cause) {
+            throw new AccountDecodeError('atlasRewardConfig', account.address, cause);
+        }
+    },
+    discriminator: CONFIG_DISCRIMINATOR,
+    minimumDataLength: CONFIG_DATA_LENGTH,
+    programAddress: SAGE_PROGRAM_ADDRESS,
+    type: 'atlasRewardConfig',
+    validate(account) {
+        validate(account, 'atlasRewardConfig', CONFIG_DISCRIMINATOR, CONFIG_DATA_LENGTH, true);
+    },
+});
+export const atlasRewardTreasuryAccountDefinition = Object.freeze({
+    decode(account) {
+        validate(account, 'atlasRewardTreasury', TREASURY_DISCRIMINATOR, TREASURY_MINIMUM_DATA_LENGTH, false);
+        return translateTreasury(decodeExactly(account, 'atlasRewardTreasury', (bytes, offset) => getAtlasRewardTreasuryDecoder().read(bytes, offset)));
+    },
+    discriminator: TREASURY_DISCRIMINATOR,
+    minimumDataLength: TREASURY_MINIMUM_DATA_LENGTH,
+    programAddress: SAGE_PROGRAM_ADDRESS,
+    type: 'atlasRewardTreasury',
+    validate(account) {
+        validate(account, 'atlasRewardTreasury', TREASURY_DISCRIMINATOR, TREASURY_MINIMUM_DATA_LENGTH, false);
+    },
+});
+function translateRewardLoot(account, value) {
+    assertLootLayout(account, value);
+    const reward = value.rewardStatus === 0
+        ? { kind: 'none' }
+        : {
+            committedAtUnixSeconds: value.rewardCommittedAt,
+            configVersion: value.rewardConfigVersion,
+            ...(value.rewardStatus === 1
+                ? { kind: 'committed' }
+                : value.rewardStatus === 2
+                    ? { kind: 'resolved' }
+                    : { kind: 'unknown', rawStatus: value.rewardStatus }),
+            legs: value.rewardLegs.slice(0, value.rewardLegCount).map((leg) => ({
+                medallionsRaw: leg.medallions,
+                recipient: leg.recipient,
+                salvageTargetValueAtlasRaw: leg.salvageTargetValue,
+            })),
+            slot: value.rewardCommitSlot,
+        };
+    return {
+        game: value.gameId,
+        profile: value.profile,
+        reward,
+        version: value.version,
+    };
+}
+export const rewardLootAccountDefinition = Object.freeze({
+    decode(account) {
+        validate(account, 'loot', REWARD_LOOT_DISCRIMINATOR, LOOT_MINIMUM_DATA_LENGTH, false);
+        return translateRewardLoot(account, decodeExactly(account, 'loot', (bytes, offset) => getLootDecoder().read(bytes, offset)));
+    },
+    discriminator: REWARD_LOOT_DISCRIMINATOR,
+    minimumDataLength: LOOT_MINIMUM_DATA_LENGTH,
+    programAddress: SAGE_PROGRAM_ADDRESS,
+    type: 'loot',
+    validate(account) {
+        validate(account, 'loot', REWARD_LOOT_DISCRIMINATOR, LOOT_MINIMUM_DATA_LENGTH, false);
+    },
+});
+export function buildRewardLootDiscoveryFilters(game, profile) {
+    return Object.freeze([
+        {
+            bytes: new Uint8Array(LOOT_DISCRIMINATOR),
+            offset: LOOT_FILTER_OFFSETS.discriminator,
+        },
+        {
+            bytes: new Uint8Array(getAddressEncoder().encode(game)),
+            offset: LOOT_FILTER_OFFSETS.game,
+        },
+        {
+            bytes: new Uint8Array(getAddressEncoder().encode(profile)),
+            offset: LOOT_FILTER_OFFSETS.profile,
+        },
+    ]);
+}
+export async function discoverRewardLootAccounts(context, profile, options = {}) {
+    const game = context.game;
+    if (game === undefined)
+        throw new MissingGameContextError();
+    const candidates = await context.data.discover(rewardLootAccountDefinition, {
+        ...options,
+        filters: buildRewardLootDiscoveryFilters(game, profile),
+        strategy: 'targeted-program-accounts',
+    });
+    for (const candidate of candidates) {
+        if (candidate.data.game !== game || candidate.data.profile !== profile) {
+            throw new AccountDecodeError('loot', candidate.address, new RangeError('Decoded Loot fields contradicted reward discovery filters.'), `Loot ${candidate.address} does not belong to the requested Game ${game} and Profile ${profile}. Refresh discovery and verify the configured Game and Profile before retrying.`);
+        }
+    }
+    return candidates;
+}
+export async function deriveAtlasRewardRegistryAddress(game) {
+    const [address] = await getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            getBytesEncoder().encode(new TextEncoder().encode('AtlasRewardRegistry')),
+            getAddressEncoder().encode(game),
+        ],
+    });
+    return address;
+}
+export { deriveAtlasRewardConfigAddress };
+export async function deriveAtlasRewardTreasuryAddress(game) {
+    const [address] = await getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            getBytesEncoder().encode(new TextEncoder().encode('AtlasRewardTreasury')),
+            getAddressEncoder().encode(game),
+        ],
+    });
+    return address;
+}
+//# sourceMappingURL=rewards.js.map

package/dist/internal/c4/rewards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewards.js","sourceRoot":"","sources":["../../../src/internal/c4/rewards.ts"],"names":[],"mappings":"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"}

package/dist/internal/c4/scanning.d.ts

@@ -0,0 +1,85 @@
+import type { Address, DiscoveryRequest, ProgramAccountFilter, SageContext, SnapshotEnvelope } from '../../client/contracts.js';
+import type { C4AccountAdapter } from './adapter.js';
+/** Stable ScanPattern offsets verified against the pinned generated codec. */
+export declare const SCAN_PATTERN_FILTER_OFFSETS: Readonly<{
+    discriminator: 0;
+    game: 76;
+}>;
+/** Audited read and deferred-action relationships for scanning. */
+export declare const SCANNING_RELATIONSHIPS: readonly [{
+    readonly from: "game + pattern id";
+    readonly kind: "derived";
+    readonly mechanism: "ScanPattern PDA seeds";
+    readonly to: "scanPattern";
+}, {
+    readonly from: "scanPattern | fleet | character";
+    readonly kind: "stored";
+    readonly mechanism: "cargo/research ids, Fleet cooldown, and Character data-runner state";
+    readonly to: "cargo | research tags | scanning state";
+}, {
+    readonly from: "scanPattern";
+    readonly kind: "nested";
+    readonly mechanism: "costs, loot outcomes, requirements, and noise maps";
+    readonly to: "scan configuration";
+}, {
+    readonly from: "scanning";
+    readonly kind: "instruction-only";
+    readonly mechanism: "scan execution and cargo/crew co-accounts are not durable relations";
+    readonly to: "actions";
+}, {
+    readonly from: "game";
+    readonly kind: "discovered";
+    readonly mechanism: "targeted ScanPattern discriminator and Game filters";
+    readonly to: "scanPattern[]";
+}];
+export interface ScanFixedValueData {
+    readonly value: number;
+    readonly raw: bigint;
+}
+export interface ScanPatternCostData {
+    readonly cargoId: number;
+    readonly multiplier: ScanFixedValueData;
+}
+export interface ScanPatternLootData {
+    readonly outputCargoId: number;
+    readonly outputAmountRaw: bigint;
+    readonly threshold: ScanFixedValueData;
+    readonly rollWeight: ScanFixedValueData;
+    readonly xpValue: ScanFixedValueData;
+    readonly researchRequirementTagIds: readonly number[];
+}
+export interface ScanNoiseMapData {
+    readonly noiseMapType: number;
+    readonly noisePowerFunction: number;
+    readonly xMultiplier: ScanFixedValueData;
+    readonly yMultiplier: ScanFixedValueData;
+    readonly zMultiplier: ScanFixedValueData;
+    readonly xCenter: ScanFixedValueData;
+    readonly yCenter: ScanFixedValueData;
+    readonly originMaxDistance: ScanFixedValueData;
+    readonly weight: ScanFixedValueData;
+    readonly seedOffset: number;
+}
+/** Fully translated ScanPattern account data before cargo resolution. */
+export interface ScanPatternAccountData {
+    readonly version: number;
+    readonly bump: number;
+    readonly id: number;
+    readonly name: string;
+    readonly game: Address;
+    readonly cooldownMultiplier: ScanFixedValueData;
+    readonly blankWeight: ScanFixedValueData;
+    readonly blankXpValue: ScanFixedValueData;
+    readonly status: 'draft' | 'active';
+    readonly costs: readonly ScanPatternCostData[];
+    readonly loot: readonly ScanPatternLootData[];
+    readonly noiseMaps: readonly ScanNoiseMapData[];
+}
+export declare const scanPatternAccountDefinition: C4AccountAdapter<ScanPatternAccountData>;
+/** Derives one ScanPattern address from Game and u16 pattern id. */
+export declare function deriveScanPatternAddress(game: Address, patternId: number): Promise<Address>;
+/** Builds stable targeted filters for the ScanPattern catalog of one Game. */
+export declare function buildScanPatternDiscoveryFilters(game: Address): readonly ProgramAccountFilter[];
+/** Discovers ScanPatterns by stable Game fields and revalidates every hint. */
+export declare function discoverScanPatternAccounts(context: SageContext, options?: Omit<DiscoveryRequest, 'filters' | 'strategy'>): Promise<readonly SnapshotEnvelope<ScanPatternAccountData>[]>;
+//# sourceMappingURL=scanning.d.ts.map

package/dist/internal/c4/scanning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanning.d.ts","sourceRoot":"","sources":["../../../src/internal/c4/scanning.ts"],"names":[],"mappings":"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"}

package/dist/internal/c4/scanning.js

@@ -0,0 +1,180 @@
+import { SCAN_PATTERN_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, ScanPatternStatus, getScanPatternDecoder, } from '@staratlas/dev-sage';
+import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, getU16Encoder, } from '@solana/kit';
+import { AccountDecodeError, InvalidEntityIdError, InvalidAccountOwnerError, InvalidDiscriminatorError, MissingGameContextError, } from '../../client/errors.js';
+const SCAN_PATTERN_MINIMUM_DATA_LENGTH = 133;
+const SCAN_PATTERN_ACCOUNT_DISCRIMINATOR = Object.freeze(Array.from(SCAN_PATTERN_DISCRIMINATOR));
+/** Stable ScanPattern offsets verified against the pinned generated codec. */
+export const SCAN_PATTERN_FILTER_OFFSETS = Object.freeze({
+    discriminator: 0,
+    game: 76,
+});
+/** Audited read and deferred-action relationships for scanning. */
+export const SCANNING_RELATIONSHIPS = Object.freeze([
+    {
+        from: 'game + pattern id',
+        kind: 'derived',
+        mechanism: 'ScanPattern PDA seeds',
+        to: 'scanPattern',
+    },
+    {
+        from: 'scanPattern | fleet | character',
+        kind: 'stored',
+        mechanism: 'cargo/research ids, Fleet cooldown, and Character data-runner state',
+        to: 'cargo | research tags | scanning state',
+    },
+    {
+        from: 'scanPattern',
+        kind: 'nested',
+        mechanism: 'costs, loot outcomes, requirements, and noise maps',
+        to: 'scan configuration',
+    },
+    {
+        from: 'scanning',
+        kind: 'instruction-only',
+        mechanism: 'scan execution and cargo/crew co-accounts are not durable relations',
+        to: 'actions',
+    },
+    {
+        from: 'game',
+        kind: 'discovered',
+        mechanism: 'targeted ScanPattern discriminator and Game filters',
+        to: 'scanPattern[]',
+    },
+]);
+function fixed(value) {
+    return { raw: value.raw, value: value.toNumber() };
+}
+function hasDiscriminator(data, discriminator) {
+    return discriminator.every((byte, index) => data[index] === byte);
+}
+function validateScanPatternAccount(account) {
+    if (account.owner !== SAGE_PROGRAM_ADDRESS) {
+        throw new InvalidAccountOwnerError('scanPattern', account.address, SAGE_PROGRAM_ADDRESS, account.owner);
+    }
+    if (account.data.length < SCAN_PATTERN_ACCOUNT_DISCRIMINATOR.length ||
+        !hasDiscriminator(account.data, SCAN_PATTERN_ACCOUNT_DISCRIMINATOR)) {
+        throw new InvalidDiscriminatorError('scanPattern', account.address);
+    }
+    if (account.data.length < SCAN_PATTERN_MINIMUM_DATA_LENGTH) {
+        throw new AccountDecodeError('scanPattern', account.address, new RangeError(`Expected at least ${SCAN_PATTERN_MINIMUM_DATA_LENGTH} ScanPattern account bytes, received ${account.data.length}.`));
+    }
+}
+function decodeExactly(account) {
+    try {
+        const [decoded, offset] = getScanPatternDecoder().read(account.data, 0);
+        if (offset !== account.data.length) {
+            throw new RangeError(`Decoded ${offset} of ${account.data.length} ScanPattern account bytes; trailing bytes are not accepted.`);
+        }
+        return decoded;
+    }
+    catch (cause) {
+        throw new AccountDecodeError('scanPattern', account.address, cause);
+    }
+}
+function status(value) {
+    switch (value) {
+        case ScanPatternStatus.Draft:
+            return 'draft';
+        case ScanPatternStatus.Active:
+            return 'active';
+    }
+}
+function translateScanPattern(account, value) {
+    for (const entry of value.lootTable) {
+        if (entry.researchRequirementCount > entry.researchRequirements.length) {
+            throw new AccountDecodeError('scanPattern', account.address, new RangeError('ScanPattern research requirement count exceeds its fixed list.'), `ScanPattern ${account.address} contains inconsistent research requirements. Refresh the account and verify the pinned binding version before retrying.`);
+        }
+    }
+    return {
+        blankWeight: fixed(value.blankWeight),
+        blankXpValue: fixed(value.blankXpValue),
+        bump: value.bump,
+        cooldownMultiplier: fixed(value.cooldownMultiplier),
+        costs: value.cost.map((cost) => ({
+            cargoId: cost.cargo,
+            multiplier: fixed(cost.costMultiplier),
+        })),
+        game: value.gameId,
+        id: value.scanPatternId,
+        loot: value.lootTable.map((entry) => ({
+            outputAmountRaw: entry.outputAmount,
+            outputCargoId: entry.output,
+            researchRequirementTagIds: entry.researchRequirements.slice(0, entry.researchRequirementCount),
+            rollWeight: fixed(entry.rollWeight),
+            threshold: fixed(entry.threshold),
+            xpValue: fixed(entry.xpValue),
+        })),
+        name: value.name.replace(/\0/gu, '').trim(),
+        noiseMaps: value.noiseMaps.map((noise) => ({
+            noiseMapType: noise.noiseMapType,
+            noisePowerFunction: noise.noisePowerFunction,
+            originMaxDistance: fixed(noise.originMaxDistance),
+            seedOffset: noise.seedOffset,
+            weight: fixed(noise.weight),
+            xCenter: fixed(noise.xCenter),
+            xMultiplier: fixed(noise.xMultiplier),
+            yCenter: fixed(noise.yCenter),
+            yMultiplier: fixed(noise.yMultiplier),
+            zMultiplier: fixed(noise.zMultiplier),
+        })),
+        status: status(value.status),
+        version: value.version,
+    };
+}
+export const scanPatternAccountDefinition = Object.freeze({
+    decode(account) {
+        validateScanPatternAccount(account);
+        return translateScanPattern(account, decodeExactly(account));
+    },
+    discriminator: SCAN_PATTERN_ACCOUNT_DISCRIMINATOR,
+    minimumDataLength: SCAN_PATTERN_MINIMUM_DATA_LENGTH,
+    programAddress: SAGE_PROGRAM_ADDRESS,
+    type: 'scanPattern',
+    validate: validateScanPatternAccount,
+});
+/** Derives one ScanPattern address from Game and u16 pattern id. */
+export async function deriveScanPatternAddress(game, patternId) {
+    if (!Number.isInteger(patternId) || patternId < 0 || patternId > 65_535) {
+        throw new InvalidEntityIdError('scanPattern', patternId);
+    }
+    const [address] = await getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            getBytesEncoder().encode(new Uint8Array([83, 99, 97, 110, 80, 97, 116, 116, 101, 114, 110])),
+            getAddressEncoder().encode(game),
+            getU16Encoder().encode(patternId),
+        ],
+    });
+    return address;
+}
+/** Builds stable targeted filters for the ScanPattern catalog of one Game. */
+export function buildScanPatternDiscoveryFilters(game) {
+    return Object.freeze([
+        {
+            bytes: new Uint8Array(SCAN_PATTERN_DISCRIMINATOR),
+            offset: SCAN_PATTERN_FILTER_OFFSETS.discriminator,
+        },
+        {
+            bytes: new Uint8Array(getAddressEncoder().encode(game)),
+            offset: SCAN_PATTERN_FILTER_OFFSETS.game,
+        },
+    ]);
+}
+/** Discovers ScanPatterns by stable Game fields and revalidates every hint. */
+export async function discoverScanPatternAccounts(context, options = {}) {
+    const game = context.game;
+    if (game === undefined)
+        throw new MissingGameContextError();
+    const patterns = await context.data.discover(scanPatternAccountDefinition, {
+        ...options,
+        filters: buildScanPatternDiscoveryFilters(game),
+        strategy: 'targeted-program-accounts',
+    });
+    for (const candidate of patterns) {
+        if (candidate.data.game !== game) {
+            throw new AccountDecodeError('scanPattern', candidate.address, new RangeError('The decoded ScanPattern Game contradicted discovery filters.'), `A discovered ScanPattern candidate did not match configured Game ${game} after decoding. Verify the provider, cluster, and pinned ScanPattern filter offsets before retrying.`);
+        }
+    }
+    return patterns;
+}
+//# sourceMappingURL=scanning.js.map

package/dist/internal/c4/scanning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanning.js","sourceRoot":"","sources":["../../../src/internal/c4/scanning.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,wBAAwB,EACxB,aAAa,GACd,MAAM,aAAa,CAAC;AAUrB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,gCAAgC,GAAG,GAAG,CAAC;AAC7C,MAAM,kCAAkC,GAAG,MAAM,CAAC,MAAM,CACtD,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CACvC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,CAAC;IACvD,aAAa,EAAE,CAAC;IAChB,IAAI,EAAE,EAAE;CACT,CAAC,CAAC;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD;QACE,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,SAAS;QACf,SAAS,EAAE,uBAAuB;QAClC,EAAE,EAAE,aAAa;KAClB;IACD;QACE,IAAI,EAAE,iCAAiC;QACvC,IAAI,EAAE,QAAQ;QACd,SAAS,EACP,qEAAqE;QACvE,EAAE,EAAE,wCAAwC;KAC7C;IACD;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,oDAAoD;QAC/D,EAAE,EAAE,oBAAoB;KACzB;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,kBAAkB;QACxB,SAAS,EACP,qEAAqE;QACvE,EAAE,EAAE,SAAS;KACd;IACD;QACE,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,YAAY;QAClB,SAAS,EAAE,qDAAqD;QAChE,EAAE,EAAE,eAAe;KACpB;CACO,CAAC,CAAC;AAkDZ,SAAS,KAAK,CAAC,KAAmD;IAChE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,gBAAgB,CACvB,IAAgB,EAChB,aAAgC;IAEhC,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,0BAA0B,CAAC,OAAmB;IACrD,IAAI,OAAO,CAAC,KAAK,KAAK,oBAAoB,EAAE,CAAC;QAC3C,MAAM,IAAI,wBAAwB,CAChC,aAAa,EACb,OAAO,CAAC,OAAO,EACf,oBAAoB,EACpB,OAAO,CAAC,KAAK,CACd,CAAC;IACJ,CAAC;IACD,IACE,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,kCAAkC,CAAC,MAAM;QAC/D,CAAC,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,kCAAkC,CAAC,EACnE,CAAC;QACD,MAAM,IAAI,yBAAyB,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,gCAAgC,EAAE,CAAC;QAC3D,MAAM,IAAI,kBAAkB,CAC1B,aAAa,EACb,OAAO,CAAC,OAAO,EACf,IAAI,UAAU,CACZ,qBAAqB,gCAAgC,wCAAwC,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CACpH,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,OAAmB;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,qBAAqB,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACxE,IAAI,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,IAAI,UAAU,CAClB,WAAW,MAAM,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,8DAA8D,CAC1G,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,kBAAkB,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,KAAwB;IACtC,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,iBAAiB,CAAC,KAAK;YAC1B,OAAO,OAAO,CAAC;QACjB,KAAK,iBAAiB,CAAC,MAAM;YAC3B,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAC3B,OAAmB,EACnB,KAAkB;IAElB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,wBAAwB,GAAG,KAAK,CAAC,oBAAoB,CAAC,MAAM,EAAE,CAAC;YACvE,MAAM,IAAI,kBAAkB,CAC1B,aAAa,EACb,OAAO,CAAC,OAAO,EACf,IAAI,UAAU,CACZ,gEAAgE,CACjE,EACD,eAAe,OAAO,CAAC,OAAO,0HAA0H,CACzJ,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;QACrC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC;QACvC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,kBAAkB,EAAE,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC;QACnD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC/B,OAAO,EAAE,IAAI,CAAC,KAAK;YACnB,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC;SACvC,CAAC,CAAC;QACH,IAAI,EAAE,KAAK,CAAC,MAAM;QAClB,EAAE,EAAE,KAAK,CAAC,aAAa;QACvB,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACpC,eAAe,EAAE,KAAK,CAAC,YAAY;YACnC,aAAa,EAAE,KAAK,CAAC,MAAM;YAC3B,yBAAyB,EAAE,KAAK,CAAC,oBAAoB,CAAC,KAAK,CACzD,CAAC,EACD,KAAK,CAAC,wBAAwB,CAC/B;YACD,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;YACnC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;YACjC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;QAC3C,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACzC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;YAC5C,iBAAiB,EAAE,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC;YACjD,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;YAC3B,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;YAC7B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;YACrC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;YAC7B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;YACrC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;SACtC,CAAC,CAAC;QACH,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,4BAA4B,GACvC,MAAM,CAAC,MAAM,CAAC;IACZ,MAAM,CAAC,OAAmB;QACxB,0BAA0B,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO,oBAAoB,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,aAAa,EAAE,kCAAkC;IACjD,iBAAiB,EAAE,gCAAgC;IACnD,cAAc,EAAE,oBAAoB;IACpC,IAAI,EAAE,aAAa;IACnB,QAAQ,EAAE,0BAA0B;CACrC,CAAC,CAAC;AAEL,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAAa,EACb,SAAiB;IAEjB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,GAAG,MAAM,EAAE,CAAC;QACxE,MAAM,IAAI,oBAAoB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,wBAAwB,CAAC;QAC/C,cAAc,EAAE,oBAAoB;QACpC,KAAK,EAAE;YACL,eAAe,EAAE,CAAC,MAAM,CACtB,IAAI,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CACnE;YACD,iBAAiB,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;YAChC,aAAa,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;SAClC;KACF,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gCAAgC,CAC9C,IAAa;IAEb,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB;YACE,KAAK,EAAE,IAAI,UAAU,CAAC,0BAA0B,CAAC;YACjD,MAAM,EAAE,2BAA2B,CAAC,aAAa;SAClD;QACD;YACE,KAAK,EAAE,IAAI,UAAU,CAAC,iBAAiB,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACvD,MAAM,EAAE,2BAA2B,CAAC,IAAI;SACzC;KACF,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAoB,EACpB,UAA0D,EAAE;IAE5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,uBAAuB,EAAE,CAAC;IAC5D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,4BAA4B,EAAE;QACzE,GAAG,OAAO;QACV,OAAO,EAAE,gCAAgC,CAAC,IAAI,CAAC;QAC/C,QAAQ,EAAE,2BAA2B;KACtC,CAAC,CAAC;IACH,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;QACjC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACjC,MAAM,IAAI,kBAAkB,CAC1B,aAAa,EACb,SAAS,CAAC,OAAO,EACjB,IAAI,UAAU,CACZ,8DAA8D,CAC/D,EACD,oEAAoE,IAAI,uGAAuG,CAChL,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}