@aephia/atlas-kit 0.5.0 → 0.6.0-next.2

package/dist/loyalty/actions/index.js

@@ -0,0 +1,159 @@
+import { getAddressEncoder, isAddress } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { deriveLoyaltyAtlasBankAddress, deriveLoyaltyFactionAddress, loyaltyAtlasBankAccountDefinition, } from '../../internal/c4/loyalty.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { adaptClaimLoyaltyAtlasInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { createPlan, } from '../../planning/index.js';
+function invalid(field, value, acceptedRange, remedy) {
+    throw new InvalidActionInputError(field, value, acceptedRange, remedy);
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function record(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalid(field, value, 'a plain object', `Provide ${field} as the documented object before retrying.`);
+    }
+    return value;
+}
+function exactKeys(value, field, required, optional = []) {
+    const accepted = new Set([...required, ...optional]);
+    const missing = required.find((key) => !Object.hasOwn(value, key));
+    const unexpected = Object.keys(value).find((key) => !accepted.has(key));
+    if (missing !== undefined || unexpected !== undefined) {
+        invalid(field, missing === undefined ? unexpected : `missing ${missing}`, `exactly the fields ${[...required, ...optional].join(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
+    }
+}
+function address(value, field) {
+    if (typeof value !== 'string' || !isAddress(value)) {
+        return invalid(field, value, 'one valid z.ink/Solana account address', `Set ${field} to the documented public account address before retrying.`);
+    }
+    return value;
+}
+function validateOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['atUnixSeconds', 'authorization']);
+    const authorizationRecord = record(options.authorization, 'authorization');
+    exactKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
+    const authorization = authorizationRecord;
+    address(authorization.profile, 'authorization.profile');
+    address(authorization.authority, 'authorization.authority');
+    if (authorization.certificate !== undefined) {
+        address(authorization.certificate, 'authorization.certificate');
+    }
+    validatePlanAuthorization(authorization);
+    if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
+        invalid('atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Provide the explicit current Unix timestamp used to evaluate Loyalty ATLAS Bank expiry before retrying.');
+    }
+    return { atUnixSeconds: options.atUnixSeconds, authorization };
+}
+function requireAccount(account, accountAddress, message) {
+    return account ?? fail(message, accountAddress);
+}
+async function hashAccountState(account) {
+    const owner = getAddressEncoder().encode(account.owner);
+    const canonical = new Uint8Array(owner.length + account.data.length);
+    canonical.set(owner);
+    canonical.set(account.data, owner.length);
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', canonical));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+async function precondition(account, describes) {
+    return Object.freeze({
+        address: account.address,
+        dataHash: await hashAccountState(account),
+        describes,
+        kind: 'account-state',
+    });
+}
+/** Plans one full Loyalty ATLAS Bank claim without signing or writes.
+ *
+ * Permission, final freshness, and concurrent claims remain
+ * chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const bank: LoyaltyAtlasBankSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planClaimLoyaltyAtlas(ctx, bank, {
+ *   atUnixSeconds: 1_786_000_000n,
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planClaimLoyaltyAtlas(ctx, bank, input) {
+    const options = validateOptions(input);
+    const game = requireGameAddress(ctx);
+    if (bank.game.address !== game) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not match the configured Game ${game}. Refresh the Bank through this context and retry.`, bank.address);
+    }
+    if (bank.profile.address !== options.authorization.profile) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not belong to authorization Profile ${options.authorization.profile}. Choose that Profile's Bank, refresh it, and retry.`, bank.address);
+    }
+    const canonicalBank = await deriveLoyaltyAtlasBankAddress(game, options.authorization.profile, bank.factionId);
+    if (bank.address !== canonicalBank) {
+        fail(`Loyalty ATLAS Bank ${bank.address} is not the canonical Loyalty ATLAS Bank ${canonicalBank} for authorization Profile ${options.authorization.profile} and faction ${String(bank.factionId)}. Refresh the Bank and retry.`, bank.address);
+    }
+    const faction = await deriveLoyaltyFactionAddress(game, bank.factionId);
+    if (bank.faction.address !== faction) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not match canonical faction account ${faction}. Refresh the Bank and retry.`, bank.address);
+    }
+    if (bank.claimableAtlasRaw === 0n) {
+        fail(`Loyalty ATLAS Bank ${bank.address} has no claimable ATLAS. Refresh it and retry after ATLAS is credited.`, bank.address);
+    }
+    if (bank.expiresAtUnixSeconds !== 0n &&
+        options.atUnixSeconds >= bank.expiresAtUnixSeconds) {
+        fail(`Loyalty ATLAS Bank ${bank.address} expired at Unix timestamp ${String(bank.expiresAtUnixSeconds)}. This balance cannot be claimed; refresh the Bank before choosing another action.`, bank.address);
+    }
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const [bankCandidate, characterCandidate] = await readContextRawAccounts(ctx, [bank.address, character]);
+    const bankAccount = requireAccount(bankCandidate, bank.address, `Loyalty ATLAS Bank ${bank.address} is missing. Refresh it and retry the claim.`);
+    const characterAccount = requireAccount(characterCandidate, character, `Canonical Character ${character} is missing for authorization Profile ${options.authorization.profile}. Refresh the Profile Character and retry the claim.`);
+    const currentBank = loyaltyAtlasBankAccountDefinition.decode(bankAccount);
+    const currentCharacter = characterAccountDefinition.decode(characterAccount);
+    if (bankAccount.address !== bank.address ||
+        currentBank.version !== bank.version ||
+        currentBank.bump !== bank.bump ||
+        currentBank.game !== game ||
+        currentBank.profile !== options.authorization.profile ||
+        currentBank.factionId !== bank.factionId ||
+        currentBank.claimableAtlasRaw !== bank.claimableAtlasRaw ||
+        currentBank.lifetimeLpRaw !== bank.lifetimeLpRaw ||
+        currentBank.lifetimeAtlasRaw !== bank.lifetimeAtlasRaw ||
+        currentBank.lastCreditedAtUnixSeconds !== bank.lastCreditedAtUnixSeconds ||
+        currentBank.expiresAtUnixSeconds !== bank.expiresAtUnixSeconds) {
+        fail(`Loyalty ATLAS Bank ${bank.address} changed or does not match its canonical Game, Profile, faction, balance, lifetime, credit, or expiry state. Refresh the Bank through this context and retry.`, bank.address);
+    }
+    if (characterAccount.address !== character ||
+        currentCharacter.playerProfile !== options.authorization.profile ||
+        currentCharacter.game !== game) {
+        fail(`Canonical Character ${character} does not match Profile ${options.authorization.profile} and configured Game ${game}. Refresh or repair the Character relationship before retrying.`, character);
+    }
+    const description = `Claim ${String(bank.claimableAtlasRaw)} raw ATLAS from Loyalty ATLAS Bank ${bank.address} to Character ${character}; permission, final freshness, and concurrent claims remain chain-authoritative.`;
+    return createPlan({
+        kind: 'loyalty.claim-atlas',
+        preconditions: await Promise.all([
+            precondition(bankAccount, `Loyalty ATLAS Bank ${bank.address} retains its validated Game, Profile, faction, positive full balance, credit, and expiry state.`),
+            precondition(characterAccount, `Character ${character} remains the canonical Character for Profile ${options.authorization.profile} and the configured Game.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptClaimLoyaltyAtlasInstruction({
+                    authorization: options.authorization,
+                    bank: bank.address,
+                    character,
+                    factionId: bank.factionId,
+                    game,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/loyalty/actions/index.js.map

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

package/dist/markets/actions/index.d.ts

@@ -0,0 +1,100 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { EntityRef } from '../../client/refs.js';
+import { type PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
+import { type Plan } from '../../planning/index.js';
+import type { LocalMarketSnapshot } from '../index.js';
+export type { PlanAuthorization };
+/** Inputs for placing one exact Local Market order.
+ *
+ * `priceRaw` is the positive raw ATLAS price per cargo unit and `quantity` is
+ * the positive raw cargo quantity. Both values are unsigned-u64 integers.
+ *
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanPlaceLocalMarketOrderOptions = {
+ *   authorization,
+ *   side: 'bid',
+ *   priceRaw: 100_000_000n,
+ *   quantity: 5n,
+ * };
+ * ```
+ */
+export interface PlanPlaceLocalMarketOrderOptions {
+    readonly authorization: PlanAuthorization;
+    readonly side: 'bid' | 'ask';
+    readonly priceRaw: bigint;
+    readonly quantity: bigint;
+}
+/** Inputs for cancelling owned Local Market orders and withdrawing filled escrow.
+ *
+ * `orderIds` is a dense, unique list of non-negative safe integers. Pass an
+ * empty list to request withdrawal of filled escrow without cancelling an open
+ * order. The chain remains authoritative about whether escrow is available.
+ *
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanCancelLocalMarketOrdersOptions = {
+ *   authorization,
+ *   orderIds: [4, 9],
+ * };
+ * ```
+ */
+export interface PlanCancelLocalMarketOrdersOptions {
+    readonly authorization: PlanAuthorization;
+    readonly orderIds: readonly number[];
+}
+interface StarbasePlayerSnapshot {
+    readonly kind: 'starbasePlayer';
+    readonly address: Address;
+    readonly playerProfile: EntityRef<'profile'>;
+    readonly system: EntityRef<'starSystem'>;
+    readonly character: EntityRef<'character'>;
+    readonly sequenceId: bigint;
+    readonly cargo: {
+        readonly items: readonly {
+            readonly id: number;
+            readonly name: string;
+            readonly quantityRaw: bigint;
+        }[];
+    };
+}
+/** Plans one Local Market bid or ask without signing, simulation, or writes.
+ *
+ * The planner validates the loaded Local Market and Starbase Player, their
+ * canonical Character/System/Game graph, the current market-enabled Starbase
+ * incarnation, and the known bid ATLAS or ask cargo balance. Matching, rent,
+ * final capacity, permissions, and state races remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const market: LocalMarketSnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanPlaceLocalMarketOrderOptions;
+ * const plan = await planPlaceLocalMarketOrder(ctx, market, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planPlaceLocalMarketOrder(ctx: SageContext, market: LocalMarketSnapshot, player: StarbasePlayerSnapshot, input: PlanPlaceLocalMarketOrderOptions): Promise<Plan>;
+/** Plans cancellation of owned Local Market orders and filled-escrow withdrawal.
+ *
+ * The planner validates the loaded Local Market and Starbase Player, their
+ * canonical Profile/Character/System/Game graph, and each selected order's
+ * ownership and price. An empty selection requests filled-escrow withdrawal.
+ * Final escrow availability and order races remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const market: LocalMarketSnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanCancelLocalMarketOrdersOptions;
+ * const plan = await planCancelLocalMarketOrders(ctx, market, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planCancelLocalMarketOrders(ctx: SageContext, market: LocalMarketSnapshot, player: StarbasePlayerSnapshot, input: PlanCancelLocalMarketOrdersOptions): Promise<Plan>;
+//# sourceMappingURL=index.d.ts.map

package/dist/markets/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/markets/actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAoBtD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAEL,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,SAAS;YACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;SAC9B,EAAE,CAAC;KACL,CAAC;CACH;AA2ND;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,IAAI,CAAC,CA+Nf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,IAAI,CAAC,CA8Of"}