@aephia/atlas-kit 0.6.0-next.35 → 0.6.0-next.37

package/dist/internal/planning/governance-fees.js

@@ -0,0 +1,239 @@
+import { getAddressEncoder, getProgramDerivedAddress, getU64Encoder, } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { CURRENCY_CONFIG_CACHE_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, STARBASE_GOVERNANCE_DISCRIMINATOR, STARBASE_TREASURY_DISCRIMINATOR, getCurrencyConfigCacheDecoder, getStarbaseGovernanceDecoder, getStarbaseTreasuryDecoder, } from '../c4/runtime-bindings.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+import { craftingProcessAccountDefinition, } from '../c4/crafting.js';
+function requireFee(condition, reason) {
+    if (!condition)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${reason} Refresh the Starbase fee configuration and recreate this action; ask its operator to initialize missing fee-routing accounts.`);
+}
+async function derive(literal, scope, sequence) {
+    return getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            new TextEncoder().encode(literal),
+            getAddressEncoder().encode(scope),
+            ...(sequence === undefined ? [] : [getU64Encoder().encode(sequence)]),
+        ],
+    });
+}
+function decode(raw, address, discriminator, decoder) {
+    requireFee(raw &&
+        raw.address === address &&
+        raw.owner === SAGE_PROGRAM_ADDRESS &&
+        !raw.executable, `Fee-routing account ${address} is missing or has an unexpected owner or address.`);
+    requireFee(discriminator.every((byte, index) => raw.data[index] === byte), `Fee-routing account ${address} has the wrong discriminator.`);
+    try {
+        const [value, consumed] = decoder.read(raw.data, 0);
+        requireFee(consumed === raw.data.length, `Fee-routing account ${address} has trailing bytes.`);
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof SageSdkError)
+            throw cause;
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Fee-routing account ${address} cannot be decoded. Refresh the deployment and recreate this action with supported account data.`);
+    }
+}
+function params(value) {
+    return {
+        craftingFeeBps: value.craftingFeeBps,
+        localMarketFeeBps: value.localMarketFeeBps,
+        localTreasuryShareBps: value.localTreasuryShareBps,
+        treasuryDistributionBps: value.treasuryDistributionBps,
+    };
+}
+function description(intent) {
+    const quote = intent.quote;
+    if (!quote.params)
+        return 'Legacy Crafting Process has no captured governance fee snapshot. No governed fee amount or recipient is inferred from synthetic defaults.';
+    const value = quote.params;
+    return `Fee policy source: ${quote.source}. Recipe fee multiplier: ${value.craftingFeeBps} basis points (10,000 = 1×); Local Market fee: ${value.localMarketFeeBps} basis points of executed ATLAS value; local Treasury share: ${value.localTreasuryShareBps} basis points of governed fees.${intent.process?.feeRecipient ? ` Captured original recipe recipient: ${intent.process.feeRecipient}.` : ''}${intent.treasury?.state === 'initialized' ? ` Treasury: ${intent.treasury.address}.` : ''} These rates do not predict an executed debit and can race a policy change after validation.`;
+}
+/** Resolve current fee accounts and a finite quote without creating or funding anything. */
+export async function resolveGovernanceFees(ctx, request, history) {
+    requireFee(history.intent.game === request.game &&
+        history.intent.system === request.system, 'Fee and history scopes do not match.');
+    requireFee(request.mode === 'crafting-complete'
+        ? request.process !== undefined
+        : request.process === undefined, 'The fee route has an invalid Crafting Process selection.');
+    const [governanceAddress, governanceBump] = await derive('StarbaseGovernance', request.system, request.starbaseSeqId);
+    const [cacheAddress, cacheBump] = await derive('CurrencyConfig', request.game);
+    const needsCache = request.mode !== 'crafting-start' || request.hasHab === true;
+    const firstAddresses = request.mode === 'crafting-complete'
+        ? [request.process, cacheAddress]
+        : [
+            governanceAddress,
+            ...(needsCache ? [cacheAddress] : []),
+            request.system,
+        ];
+    const read = async (addresses) => {
+        const rows = await readContextRawAccounts(ctx, addresses, {
+            commitment: 'confirmed',
+        });
+        requireFee(rows.length === addresses.length &&
+            rows.every((raw, index) => !raw ||
+                (raw.address === addresses[index] && raw.slot >= history.slot)), 'Fee-routing reads are incomplete or older than their history context.');
+        return rows;
+    };
+    const rows = await read(firstAddresses);
+    if (request.mode !== 'crafting-complete') {
+        const raw = rows[rows.length - 1];
+        requireFee(raw && !raw.executable, 'The fee route System account is missing or invalid.');
+        const system = starSystemAccountDefinition.decode(raw);
+        const canonical = await deriveStarSystemAddress(request.game, system.systemId);
+        requireFee(raw.address === request.system &&
+            canonical === request.system &&
+            system.game === request.game &&
+            system.sequenceId === request.starbaseSeqId &&
+            system.starbase !== undefined, 'The fee route System does not match its canonical address, Game or active Starbase sequence.');
+    }
+    let currencyCache;
+    if (needsCache) {
+        const value = decode(rows[1], cacheAddress, CURRENCY_CONFIG_CACHE_DISCRIMINATOR, getCurrencyConfigCacheDecoder());
+        requireFee(value.gameId === request.game && value.bump === cacheBump, 'CurrencyCache does not match the configured Game or canonical PDA bump.');
+        currencyCache = { address: cacheAddress, version: value.version };
+    }
+    let governance;
+    let process;
+    let quote;
+    let treasuryGovernance;
+    let treasuryRequired = false;
+    if (request.mode === 'crafting-complete') {
+        const raw = rows[0];
+        requireFee(raw && raw.address === request.process && !raw.executable, 'The selected Crafting Process is missing or invalid.');
+        const value = craftingProcessAccountDefinition.decode(raw);
+        requireFee(value.system === request.system &&
+            value.starbaseSequenceId === request.starbaseSeqId, 'The Crafting Process belongs to a different System or Starbase generation.');
+        process = {
+            address: request.process,
+            version: value.version,
+            ...(value.feeRecipient === undefined
+                ? {}
+                : { feeRecipient: value.feeRecipient }),
+            ...(value.feeGovernance === undefined
+                ? {}
+                : { feeGovernance: value.feeGovernance }),
+            ...(value.feeSnapshot === undefined
+                ? {}
+                : { feeSnapshot: value.feeSnapshot }),
+        };
+        quote = value.feeSnapshot
+            ? {
+                source: 'process-snapshot',
+                params: {
+                    craftingFeeBps: value.feeSnapshot.craftingFeeBasisPoints,
+                    localMarketFeeBps: value.feeSnapshot.localMarketFeeBasisPoints,
+                    localTreasuryShareBps: value.feeSnapshot.localTreasuryShareBasisPoints,
+                },
+            }
+            : { source: 'legacy-process' };
+        treasuryGovernance = value.feeGovernance;
+        treasuryRequired = treasuryGovernance !== undefined;
+    }
+    else {
+        const raw = rows[0];
+        const value = raw
+            ? decode(raw, governanceAddress, STARBASE_GOVERNANCE_DISCRIMINATOR, getStarbaseGovernanceDecoder())
+            : undefined;
+        if (value) {
+            requireFee(value.version === 2 || value.version === 3, 'Starbase governance has an unsupported schema version.');
+            requireFee(value.gameId === request.game &&
+                value.system === request.system &&
+                value.starbaseSeqId === request.starbaseSeqId &&
+                value.bump === governanceBump &&
+                value.enabled <= 1, 'Starbase governance has invalid scope, sequence, bump or enabled state.');
+            requireFee(!(value.version === 3 && history.intent.state === 'absent'), 'This Starbase governance requires initialized daily Democracy history.');
+            governance = {
+                address: governanceAddress,
+                state: 'initialized',
+                version: value.version,
+                enabled: value.enabled,
+                controllerFaction: value.controllerFaction,
+                starbaseSeqId: value.starbaseSeqId,
+                ...(history.intent.state === 'absent' && value.enabled === 1
+                    ? { activeParams: params(value.activeParams) }
+                    : {}),
+            };
+        }
+        else
+            governance = { address: governanceAddress, state: 'absent' };
+        if (history.intent.state === 'initialized')
+            quote = {
+                source: history.intent.enabled === 0
+                    ? 'history-disabled'
+                    : history.intent.generation
+                        ? 'history-generation'
+                        : 'history-policy',
+                params: params(history.intent.effectiveParams),
+            };
+        else if (value?.enabled)
+            quote = { source: 'governance', params: params(value.activeParams) };
+        else
+            quote = {
+                source: 'default',
+                params: {
+                    craftingFeeBps: 10000,
+                    localMarketFeeBps: 0,
+                    localTreasuryShareBps: 0,
+                    treasuryDistributionBps: 0,
+                },
+            };
+        if (request.mode === 'market') {
+            treasuryGovernance = governanceAddress;
+            treasuryRequired = quote.params.localTreasuryShareBps > 0;
+        }
+    }
+    let treasury;
+    if (treasuryGovernance) {
+        const [treasuryAddress, treasuryBump] = await derive('StarbaseTreasury', treasuryGovernance);
+        const [raw] = await read([treasuryAddress]);
+        if (raw) {
+            const value = decode(raw, treasuryAddress, STARBASE_TREASURY_DISCRIMINATOR, getStarbaseTreasuryDecoder());
+            requireFee(value.governance === treasuryGovernance &&
+                value.bump === treasuryBump &&
+                (request.mode !== 'market' || governance?.state === 'initialized'), 'Starbase Treasury does not match its governance or canonical PDA.');
+            treasury = {
+                address: treasuryAddress,
+                state: 'initialized',
+                version: value.version,
+                governance: value.governance,
+            };
+        }
+        else {
+            requireFee(!treasuryRequired, 'This fee route requires a Starbase Treasury that has not been initialized.');
+            treasury = { address: treasuryAddress, state: 'absent' };
+        }
+    }
+    const intent = {
+        request: { ...request },
+        ...(governance ? { governance } : {}),
+        ...(currencyCache ? { currencyCache } : {}),
+        ...(treasury ? { treasury } : {}),
+        ...(process ? { process } : {}),
+        quote,
+    };
+    return {
+        intent,
+        accounts: {
+            ...(request.mode === 'crafting-complete'
+                ? {}
+                : { starbaseGovernance: governanceAddress }),
+            ...(currencyCache ? { currencyCache: cacheAddress } : {}),
+            ...(treasury?.state === 'initialized'
+                ? { starbaseTreasury: treasury.address }
+                : {}),
+        },
+        description: description(intent),
+    };
+}
+/** Compare finite serialized fields; mutable shared balances are deliberately absent. */
+export function matchGovernanceFeesIntent(expected, actual) {
+    const canonical = (value) => JSON.stringify(value, (_key, field) => typeof field === 'bigint'
+        ? field.toString()
+        : field && typeof field === 'object' && !Array.isArray(field)
+            ? Object.fromEntries(Object.entries(field).sort(([left], [right]) => left.localeCompare(right)))
+            : field);
+    return canonical(expected) === canonical(actual);
+}
+//# sourceMappingURL=governance-fees.js.map

package/dist/internal/planning/governance-fees.js.map

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

package/dist/internal/planning/runtime-guards.d.ts

@@ -0,0 +1,43 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+import { type HistoryIntent, type ResolvedDemocracyHistory } from './democracy-history.js';
+import { type XpRuntimeIntent, type XpRuntimeAccounts } from './xp-runtime.js';
+import { resolveGovernanceFees, type FeeIntent } from './governance-fees.js';
+type FeeAccounts = Awaited<ReturnType<typeof resolveGovernanceFees>>['accounts'];
+type BaseGuard = {
+    readonly address: Address;
+    readonly describes: string;
+    readonly dataHash?: never;
+};
+/** Finite runtime eligibility and consumed fee routes, excluding changing balances. */
+export type RuntimeGuard = BaseGuard & ({
+    readonly kind: 'democracy-history';
+    readonly intent: HistoryIntent;
+    readonly accounts: ResolvedDemocracyHistory['accounts'];
+} | {
+    readonly kind: 'xp-runtime';
+    readonly intent: XpRuntimeIntent;
+    readonly accounts: XpRuntimeAccounts;
+} | {
+    readonly kind: 'governance-fees';
+    readonly intent: FeeIntent;
+    readonly accounts: FeeAccounts;
+});
+export type RuntimeWire<T> = T extends bigint ? string : T extends Address ? string : T extends object ? {
+    readonly [K in keyof T]: RuntimeWire<T[K]>;
+} : T;
+export type RuntimeGuardJson = RuntimeWire<RuntimeGuard>;
+export declare function isRuntimeGuard(value: {
+    readonly kind?: unknown;
+}): value is RuntimeGuard;
+/** Strict nested runtime parsing applies both to factory values and persisted JSON. */
+export declare function normalizeRuntimeGuard(value: unknown, field: string, wire?: boolean): RuntimeGuard;
+/** Bigints use canonical decimal strings; schema validation excludes arbitrary object graphs. */
+export declare function runtimeGuardToJSON(guard: RuntimeGuard): RuntimeGuardJson;
+/** Resolve canonical accounts again; shared balances and XP counters are not compared. */
+export declare function revalidateRuntimeGuards(ctx: SageContext, guards: readonly RuntimeGuard[]): Promise<void>;
+/** Old layouts and unguarded persisted instructions fail before assembly or signing. */
+export declare function validateRuntimeInstructions(steps: readonly PlanStep[], preconditions: readonly PlanPrecondition[]): void;
+export {};
+//# sourceMappingURL=runtime-guards.d.ts.map

package/dist/internal/planning/runtime-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-guards.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/runtime-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAGb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAgB7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EAErB,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAE9B,KAAK,WAAW,GAAG,OAAO,CACxB,UAAU,CAAC,OAAO,qBAAqB,CAAC,CACzC,CAAC,UAAU,CAAC,CAAC;AACd,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AACF,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,SAAS,GAClC,CACI;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC,UAAU,CAAC,CAAC;CACzD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC,CACJ,CAAC;AACJ,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GACzC,MAAM,GACN,CAAC,SAAS,OAAO,GACf,MAAM,GACN,CAAC,SAAS,MAAM,GACd;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAC9C,CAAC,CAAC;AACV,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;AACzD,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,KAAK,IAAI,YAAY,CAMxB;AAkLD,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,IAAI,UAAQ,GACX,YAAY,CAuDd;AACD,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,CAMxE;AAiBD,0FAA0F;AAC1F,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC,CAuCf;AAgTD,wFAAwF;AACxF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,aAAa,EAAE,SAAS,gBAAgB,EAAE,GACzC,IAAI,CAkIN"}