@aephia/atlas-kit 0.6.0-next.12 → 0.6.0-next.121

package/dist/cargo/actions/wallet-context.d.ts

@@ -1,5 +1,5 @@
-import { type Address } from '@solana/kit';
-import type { RawAccount } from '../../client/contracts.js';
+import type { Address } from '@solana/kit';
+import type { RawAccount, SageContext } from '../../client/contracts.js';
 import type { EntityRef } from '../../client/refs.js';
 import type { PlanPrecondition } from '../../planning/index.js';
 export interface StarbasePlayerIntent {
@@ -10,5 +10,54 @@ export interface StarbasePlayerIntent {
     readonly character: EntityRef<'character'>;
 }
 export declare function observeWalletAccount(account: RawAccount, role?: string): Promise<PlanPrecondition>;
-export { validateWalletCargoCache } from '../../internal/c4/wallet-cargo-cache.js';
+/** Requires an exact raw u64 amount and a u16 cargo id. */
+export declare function validateWalletCargoAmount(amount: unknown, cargoId: unknown): void;
+/** Pre-read facts shared by wallet deposits and withdrawals: the authorization
+ * Profile's canonical Starbase Player, the fresh cargo configuration, and the
+ * canonical Game cargo cache and its shared vault for the cargo mint. */
+export declare function resolveWalletCargo(ctx: SageContext, starbase: StarbasePlayerIntent, profile: Address, cargoId: number, game: Address): Promise<{
+    bump: import("@solana/kit").ProgramDerivedAddressBump;
+    cache: Address<string>;
+    character: Address;
+    config: Readonly<{
+        configHash: string;
+        rawAccount: RawAccount;
+        cargo: import("@staratlas/dev-sage").CargoType;
+        cache: import("../../client/contracts.js").Address;
+        sequenceId: number;
+    }>;
+    mint: Address;
+    player: Address;
+    system: import("../../client/contracts.js").Address;
+    vault: Address;
+}>;
+type WalletCargo = Awaited<ReturnType<typeof resolveWalletCargo>>;
+/** Requires an account read for a wallet cargo transfer to exist. */
+export declare function requireWalletAccount(account: RawAccount | undefined, address: Address, action: 'deposit' | 'withdrawal'): RawAccount;
+/** Reads the Profile, Character, Starbase Player, System, cargo cache, mint
+ * and shared vault with `extra` accounts in the same batch, and requires the
+ * shared Starbase graph, cache, mint and vault facts. Returns the extra
+ * accounts as read, missing ones included. */
+export declare function readWalletCargo(ctx: SageContext, cargo: WalletCargo, profile: Address, game: Address, action: 'deposit' | 'withdrawal', extra: readonly Address[]): Promise<{
+    cacheData: import("@staratlas/dev-sage").CargoDefinitionsCache;
+    characterRaw: RawAccount;
+    decimals: number;
+    extraAccounts: (RawAccount | undefined)[];
+    playerData: Readonly<import("../../starbases/index.js").StarbasePlayerAccountData>;
+    playerRaw: RawAccount;
+    profileRaw: RawAccount;
+    systemGuard: {
+        describes: string;
+        requireCss?: true;
+        kind: "starbase-system";
+        address: import("../../client/contracts.js").Address;
+        game: Address;
+        starbaseSequenceId: bigint;
+    };
+    vaultBalance: bigint;
+}>;
+/** The mint, cargo configuration and cargo cache guards shared by wallet
+ * cargo Plans. */
+export declare function walletCargoGuards(cargo: WalletCargo, cargoId: number, game: Address, decimals: number): readonly PlanPrecondition[];
+export {};
 //# sourceMappingURL=wallet-context.d.ts.map

package/dist/cargo/actions/wallet-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-context.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,MAAM,WAAW,oBAAoB;IACnC,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;CAC5C;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,UAAU,EACnB,IAAI,SAAiB,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAO3B;AAED,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"wallet-context.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAStD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,MAAM,WAAW,oBAAoB;IACnC,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;CAC5C;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,UAAU,EACnB,IAAI,SAAiB,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAK3B;AAED,2DAA2D;AAC3D,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,QAwB1E;AAED;;yEAEyE;AACzE,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO;;;;;;;;;;;;;;;GAyBd;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;AAElE,qEAAqE;AACrE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,GAAG,YAAY,GAC/B,UAAU,CAQZ;AAED;;;8CAG8C;AAC9C,wBAAsB,eAAe,CACnC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,SAAS,GAAG,YAAY,EAChC,KAAK,EAAE,SAAS,OAAO,EAAE;;;;;;;;;;;;;;;;;GAkE1B;AAED;kBACkB;AAClB,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,SAAS,gBAAgB,EAAE,CAyB7B"}

package/dist/cargo/actions/wallet-context.js

@@ -1,12 +1,123 @@
-import { hashAccountState } from '../../internal/planning/account-state.js';
-import {} from '@solana/kit';
+import { accountStatePrecondition } from '../../internal/planning/account-state.js';
+import { InvalidActionInputError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { validateWalletCargoCache } from '../../internal/c4/wallet-cargo-cache.js';
+import { deriveAssociatedTokenAddress, readTokenAccount, } from '../../internal/planning/original-token.js';
+import { requireProfileStarbasePlayer } from '../../internal/planning/starbase-player-owner.js';
+import { validateTokenMint } from '../../internal/planning/token-mint.js';
+import { validateWalletStarbase } from '../../internal/planning/wallet-starbase.js';
+import { readFreshGameCargoBytesConfiguration } from '../../registry/cargo.js';
+import { failWalletCargo } from './wallet-token.js';
+import { deriveCargoDefinitionsCacheAddress } from '../../internal/c4/pda.js';
 export async function observeWalletAccount(account, role = 'prerequisite') {
+    return accountStatePrecondition(account, `${role} account ${account.address} retains its observed owner and data; native balance is not guarded.`);
+}
+/** Requires an exact raw u64 amount and a u16 cargo id. */
+export function validateWalletCargoAmount(amount, cargoId) {
+    if (typeof amount !== 'bigint' ||
+        amount <= 0n ||
+        amount > 18446744073709551615n)
+        throw new InvalidActionInputError('amount', amount, 'a positive bigint in the unsigned u64 range', 'Supply an exact raw token amount as bigint.');
+    if (typeof cargoId !== 'number' ||
+        !Number.isSafeInteger(cargoId) ||
+        cargoId < 0 ||
+        cargoId > 65535)
+        throw new InvalidActionInputError('cargoId', cargoId, 'an unsigned u16 cargo ID', 'Choose an existing cargo definition ID.');
+}
+/** Pre-read facts shared by wallet deposits and withdrawals: the authorization
+ * Profile's canonical Starbase Player, the fresh cargo configuration, and the
+ * canonical Game cargo cache and its shared vault for the cargo mint. */
+export async function resolveWalletCargo(ctx, starbase, profile, cargoId, game) {
+    if (starbase.kind !== 'starbasePlayer')
+        failWalletCargo('The loaded Starbase must be a Starbase Player registration.', starbase.address);
+    const character = await requireProfileStarbasePlayer(starbase, profile, game);
+    const config = await readFreshGameCargoBytesConfiguration(ctx, cargoId);
+    const [cache, bump] = await deriveCargoDefinitionsCacheAddress(game);
+    if (config.cache !== cache)
+        failWalletCargo('The configured cargo cache does not match the canonical Game cargo-cache PDA.', config.cache);
     return {
-        kind: 'account-state',
-        address: account.address,
-        dataHash: await hashAccountState(account.owner, account.data),
-        describes: `${role} account ${account.address} retains its observed owner and data; native balance is not guarded.`,
+        bump,
+        cache,
+        character,
+        config,
+        mint: config.cargo.mint,
+        player: starbase.address,
+        system: starbase.system.address,
+        vault: await deriveAssociatedTokenAddress(cache, config.cargo.mint),
     };
 }
-export { validateWalletCargoCache } from '../../internal/c4/wallet-cargo-cache.js';
+/** Requires an account read for a wallet cargo transfer to exist. */
+export function requireWalletAccount(account, address, action) {
+    return (account ??
+        failWalletCargo(`Required ${action} account ${address} is missing. Register the player or create the required accounts separately.`, address));
+}
+/** Reads the Profile, Character, Starbase Player, System, cargo cache, mint
+ * and shared vault with `extra` accounts in the same batch, and requires the
+ * shared Starbase graph, cache, mint and vault facts. Returns the extra
+ * accounts as read, missing ones included. */
+export async function readWalletCargo(ctx, cargo, profile, game, action, extra) {
+    const addresses = [
+        profile,
+        cargo.character,
+        cargo.player,
+        cargo.system,
+        cargo.cache,
+        cargo.mint,
+        cargo.vault,
+    ];
+    const candidates = await readContextRawAccounts(ctx, [
+        ...addresses,
+        ...extra,
+    ]);
+    const [profileRaw, characterRaw, playerRaw, systemRaw, cacheRaw, mintRaw, vaultRaw,] = addresses.map((address, index) => requireWalletAccount(candidates[index], address, action));
+    const { playerData, systemGuard } = await validateWalletStarbase({
+        profile: profileRaw,
+        character: characterRaw,
+        player: playerRaw,
+        system: systemRaw,
+    }, {
+        game,
+        profile,
+        character: cargo.character,
+        system: cargo.system,
+        requireCss: action === 'deposit',
+    }, failWalletCargo);
+    return {
+        cacheData: validateWalletCargoCache(cacheRaw, game, cargo.bump),
+        characterRaw,
+        decimals: validateTokenMint(mintRaw),
+        extraAccounts: candidates.slice(addresses.length),
+        playerData,
+        playerRaw,
+        profileRaw,
+        systemGuard,
+        vaultBalance: readTokenAccount(vaultRaw, cargo.mint, cargo.cache, failWalletCargo),
+    };
+}
+/** The mint, cargo configuration and cargo cache guards shared by wallet
+ * cargo Plans. */
+export function walletCargoGuards(cargo, cargoId, game, decimals) {
+    return [
+        {
+            kind: 'token-mint',
+            address: cargo.mint,
+            decimals,
+            describes: `Mint ${cargo.mint} remains a valid initialized original Token Mint with unchanged decimals; supply and authorities may change.`,
+        },
+        {
+            kind: 'game-cargo-bytes-config',
+            address: game,
+            cargoId,
+            configHash: cargo.config.configHash,
+            describes: 'The selected cargo’s full encoded configuration, including its stored name, and cache identity remain unchanged; unrelated Game changes are allowed.',
+        },
+        {
+            kind: 'cargo-cache',
+            address: cargo.cache,
+            game,
+            bump: cargo.bump,
+            describes: 'The canonical cargo cache retains valid Game identity and layout; counters may change.',
+        },
+    ];
+}
 //# sourceMappingURL=wallet-context.js.map

package/dist/cargo/actions/wallet-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-context.js","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAgB,MAAM,aAAa,CAAC;AAY3C,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAmB,EACnB,IAAI,GAAG,cAAc;IAErB,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,MAAM,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;QAC7D,SAAS,EAAE,GAAG,IAAI,YAAY,OAAO,CAAC,OAAO,sEAAsE;KACpH,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"wallet-context.js","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-context.ts"],"names":[],"mappings":"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"}

package/dist/cargo/actions/wallet-token.d.ts

@@ -1,8 +1,3 @@
-import { type Address } from '@solana/kit';
-import type { RawAccount } from '../../client/contracts.js';
-export declare const ORIGINAL_TOKEN_PROGRAM: Address;
+import type { Address } from '@solana/kit';
 export declare function failWalletCargo(message: string, address: Address): never;
-export declare function deriveWalletTokenAddress(owner: Address, mint: Address): Promise<Address>;
-export declare function validateWalletMint(account: RawAccount): number;
-export declare function validateWalletToken(account: RawAccount, mint: Address, owner: Address): bigint;
 //# sourceMappingURL=wallet-token.d.ts.map

package/dist/cargo/actions/wallet-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-token.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,eAAO,MAAM,sBAAsB,EACgB,OAAO,CAAC;AAI3D,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,KAAK,CAMxE;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAWlB;AA6BD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAW9D;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,MAAM,CAuBR"}
+{"version":3,"file":"wallet-token.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,KAAK,CAMxE"}

package/dist/cargo/actions/wallet-token.js

@@ -1,58 +1,5 @@
-import { getAddressDecoder, getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
 import { SageSdkError } from '../../client/errors.js';
-export const ORIGINAL_TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
-const ASSOCIATED_TOKEN_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 export function failWalletCargo(message, address) {
     throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${message} Refresh the accounts or select a supported original Token account before planning again.`, { address });
 }
-export async function deriveWalletTokenAddress(owner, mint) {
-    const encode = getAddressEncoder();
-    const [result] = await getProgramDerivedAddress({
-        programAddress: ASSOCIATED_TOKEN_PROGRAM,
-        seeds: [
-            encode.encode(owner),
-            encode.encode(ORIGINAL_TOKEN_PROGRAM),
-            encode.encode(mint),
-        ],
-    });
-    return result;
-}
-function view(account, size) {
-    if (account.executable ||
-        account.owner !== ORIGINAL_TOKEN_PROGRAM ||
-        account.data.length !== size) {
-        failWalletCargo(`Account ${account.address} must have the original Token program owner and exactly ${String(size)} bytes; Token-2022 and multisig layouts are unsupported.`, account.address);
-    }
-    return new DataView(account.data.buffer, account.data.byteOffset, account.data.byteLength);
-}
-function option(view, offset, account) {
-    if (view.getUint32(offset, true) > 1) {
-        failWalletCargo(`Token account ${account.address} has an invalid optional field.`, account.address);
-    }
-}
-export function validateWalletMint(account) {
-    const bytes = view(account, 82);
-    option(bytes, 0, account);
-    option(bytes, 46, account);
-    if (bytes.getUint8(45) !== 1) {
-        failWalletCargo(`Cargo mint ${account.address} is not initialized.`, account.address);
-    }
-    return bytes.getUint8(44);
-}
-export function validateWalletToken(account, mint, owner) {
-    const bytes = view(account, 165);
-    option(bytes, 72, account);
-    option(bytes, 109, account);
-    option(bytes, 129, account);
-    if (bytes.getUint8(108) !== 1) {
-        failWalletCargo(`Token account ${account.address} must be initialized and unfrozen.`, account.address);
-    }
-    const decode = getAddressDecoder();
-    if (decode.decode(account.data.subarray(0, 32)) !== mint ||
-        decode.decode(account.data.subarray(32, 64)) !== owner) {
-        failWalletCargo(`Token account ${account.address} must contain cargo mint ${mint} and be owned internally by ${owner}; delegated spending is unsupported.`, account.address);
-    }
-    // A recorded delegate does not prevent the actual owner from transferring.
-    return bytes.getBigUint64(64, true);
-}
 //# sourceMappingURL=wallet-token.js.map

package/dist/cargo/actions/wallet-token.js.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-token.js","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-token.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wallet-token.js","sourceRoot":"","sources":["../../../src/cargo/actions/wallet-token.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,OAAgB;IAC/D,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,GAAG,OAAO,2FAA2F,EACrG,EAAE,OAAO,EAAE,CACZ,CAAC;AACJ,CAAC"}

package/dist/cargo/actions/withdrawal.d.ts

@@ -1,7 +1,7 @@
 import { type Address } from '@solana/kit';
 import type { SageContext } from '../../client/contracts.js';
 import { type PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
-import { type Plan } from '../../planning/index.js';
+import type { Plan } from '../../planning/index.js';
 import { type StarbasePlayerIntent } from './wallet-context.js';
 /** An exact withdrawal to an explicit receiving wallet, independently of Profile authority.
  * `destinationAccount` permits creating only a missing canonical ATA. An existing

package/dist/cargo/actions/withdrawal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/withdrawal.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAkBzE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAEL,KAAK,IAAI,EAGV,MAAM,yBAAyB,CAAC;AASjC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAO7B;;;;;;;;;GASG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;QACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,IAAI,CAAC,CA0Wf"}
+{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../../../src/cargo/actions/withdrawal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAQ1D,OAAO,KAAK,EAAE,IAAI,EAA8B,MAAM,yBAAyB,CAAC;AAGhF,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;QACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,IAAI,CAAC,CA2Lf"}

package/dist/cargo/actions/withdrawal.js

@@ -1,25 +1,11 @@
-import { AccountRole, getAddressEncoder, getProgramDerivedAddress, isOffCurveAddress, } from '@solana/kit';
+import { isOffCurveAddress } from '@solana/kit';
 import { InvalidActionInputError } from '../../client/errors.js';
-import { readContextRawAccounts } from '../../client/reconciliation.js';
-import { sage } from '../../internal/c4/bindings.js';
-import { characterAccountDefinition, profileAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
-import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
-import { starSystemAccountDefinition, deriveStarSystemAddress, } from '../../internal/c4/world.js';
 import { requireGameAddress } from '../../internal/game-context.js';
 import { adaptWithdrawCargoFromGameInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
-import { createPlan, } from '../../planning/index.js';
-import { readFreshGameCargoConfiguration } from '../../registry/cargo.js';
-import { deriveWalletTokenAddress, failWalletCargo, validateWalletMint, validateWalletToken, ORIGINAL_TOKEN_PROGRAM, } from './wallet-token.js';
-import { observeWalletAccount, validateWalletCargoCache, } from './wallet-context.js';
-const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
-const SYSTEM_PROGRAM = '11111111111111111111111111111111';
-const RENT_SYSVAR = 'SysvarRent111111111111111111111111111111111';
-const SYSVAR_OWNER = 'Sysvar1111111111111111111111111111111111111';
-function required(account, address) {
-    if (!account)
-        failWalletCargo(`Required withdrawal account ${address} is missing. Register the player or initialize its prerequisites separately.`, address);
-    return account;
-}
+import { TOKEN_TRANSFER_DISCLOSURE, deriveAssociatedTokenAddress, isTokenMultisig, readTokenAccount, resolveAssociatedTokenCreation, } from '../../internal/planning/original-token.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
+import { failWalletCargo } from './wallet-token.js';
+import { observeWalletAccount, readWalletCargo, resolveWalletCargo, validateWalletCargoAmount, walletCargoGuards, } from './wallet-context.js';
 /** Plans an exact game-to-wallet withdrawal without signing or submitting.
  * Current verified game/token conversion is limited to zero-decimal cargo mints.
  * The recipient never signs merely to receive tokens. ATA creation is explicit,
@@ -40,119 +26,49 @@ function required(account, address) {
  */
 export async function planWithdrawCargoFromGame(ctx, starbase, options) {
     validatePlanAuthorization(options.authorization);
-    if (typeof options.amount !== 'bigint' ||
-        options.amount <= 0n ||
-        options.amount > 18446744073709551615n)
-        throw new InvalidActionInputError('amount', options.amount, 'a positive bigint in the unsigned u64 range', 'Supply an exact raw token amount as bigint.');
-    if (!Number.isSafeInteger(options.cargoId) ||
-        options.cargoId < 0 ||
-        options.cargoId > 65535)
-        throw new InvalidActionInputError('cargoId', options.cargoId, 'an unsigned u16 cargo ID', 'Choose an existing cargo definition ID.');
+    validateWalletCargoAmount(options.amount, options.cargoId);
     const creation = options.destinationAccount;
     if (creation && (creation.mode !== 'create-if-missing' || !creation.payer))
         throw new InvalidActionInputError('destinationAccount', creation, 'create-if-missing with an explicit payer', 'Provide an address-only payer to opt into canonical ATA creation.');
     const game = requireGameAddress(ctx);
-    const character = await findCharacterPda(options.authorization.profile, game);
-    const player = await deriveStarbasePlayerAddress(starbase.system.address, character);
-    if (starbase.kind !== 'starbasePlayer' ||
-        starbase.address !== player ||
-        starbase.playerProfile.address !== options.authorization.profile ||
-        starbase.character.address !== character)
-        failWalletCargo('The loaded Starbase must belong to the authorized Profile and its canonical Character.', starbase.address);
-    const config = await readFreshGameCargoConfiguration(ctx, options.cargoId);
-    const [cache, bump] = await getProgramDerivedAddress({
-        programAddress: sage.SAGE_PROGRAM_ADDRESS,
-        seeds: [
-            new TextEncoder().encode('CargoDefinitionsCache'),
-            getAddressEncoder().encode(game),
-        ],
-    });
-    if (config.cache !== cache)
-        failWalletCargo('The configured cargo cache differs from the canonical Game cache.', config.cache);
-    const canonicalDestination = await deriveWalletTokenAddress(options.recipient, config.cargo.mint);
+    const { profile } = options.authorization;
+    const cargo = await resolveWalletCargo(ctx, starbase, profile, options.cargoId, game);
+    const canonicalDestination = await deriveAssociatedTokenAddress(options.recipient, cargo.mint);
     const destination = options.destination ?? canonicalDestination;
-    const source = await deriveWalletTokenAddress(cache, config.cargo.mint);
+    const source = cargo.vault;
     if (destination === source)
         failWalletCargo('The withdrawal destination is the shared Game vault itself. Choose a different recipient token account so the withdrawal actually transfers tokens out of the vault.', destination);
-    const addresses = [
-        options.authorization.profile,
-        character,
-        player,
-        starbase.system.address,
-        cache,
-        config.cargo.mint,
-        source,
-    ];
-    const candidates = await readContextRawAccounts(ctx, [
-        ...addresses,
+    const { cacheData, characterRaw, decimals, extraAccounts: [destinationRaw, recipientRaw], playerData, playerRaw, profileRaw, systemGuard, vaultBalance: backing, } = await readWalletCargo(ctx, cargo, profile, game, 'withdrawal', [
         destination,
         options.recipient,
     ]);
-    const accounts = addresses.map((address, index) => required(candidates[index], address));
-    const [profileRaw, characterRaw, playerRaw, systemRaw, cacheRaw, mintRaw, vaultRaw,] = accounts;
-    const destinationRaw = candidates[addresses.length];
-    const recipientRaw = candidates[addresses.length + 1];
-    profileAccountDefinition.decode(profileRaw);
-    const characterData = characterAccountDefinition.decode(characterRaw);
-    const playerData = starbasePlayerAccountDefinition.decode(playerRaw);
-    const systemData = starSystemAccountDefinition.decode(systemRaw);
-    if (characterData.game !== game ||
-        characterData.playerProfile !== options.authorization.profile ||
-        playerData.playerProfile !== options.authorization.profile ||
-        playerData.character !== character ||
-        playerData.system !== starbase.system.address ||
-        systemData.game !== game ||
-        (await deriveStarSystemAddress(game, systemData.systemId)) !==
-            starbase.system.address)
-        failWalletCargo('Fresh Profile, Character, System and player Starbase relationships do not match the configured Game.', player);
-    const cacheData = validateWalletCargoCache(cacheRaw, game, bump);
-    const decimals = validateWalletMint(mintRaw);
     if (decimals !== 0)
-        failWalletCargo('Withdrawal game/token conversion for nonzero-decimal cargo mints is not verified. Use supported zero-decimal cargo until a bindings/program review establishes conversion.', config.cargo.mint);
-    const backing = validateWalletToken(vaultRaw, config.cargo.mint, cache);
+        failWalletCargo('Withdrawal game/token conversion for nonzero-decimal cargo mints is not verified. Use supported zero-decimal cargo until a bindings/program review establishes conversion.', cargo.mint);
     if (destinationRaw)
-        validateWalletToken(destinationRaw, config.cargo.mint, options.recipient);
-    if (recipientRaw &&
-        recipientRaw.data.length === 355 &&
-        (recipientRaw.owner === ORIGINAL_TOKEN_PROGRAM ||
-            recipientRaw.owner ===
-                'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'))
+        readTokenAccount(destinationRaw, cargo.mint, options.recipient, failWalletCargo);
+    if (isTokenMultisig(recipientRaw))
         failWalletCargo('Token multisig recipients are outside the supported wallet cargo contract.', options.recipient);
     const entitlement = playerData.cargo.amounts.find((item) => item.cargoId === options.cargoId)
         ?.amount ?? 0n;
     if (entitlement < options.amount)
-        failWalletCargo(`Player Starbase cargo entitlement ${String(entitlement)} is below requested ${String(options.amount)}. Shared vault backing is not personal inventory. Reduce the amount.`, player);
+        failWalletCargo(`Player Starbase cargo entitlement ${String(entitlement)} is below requested ${String(options.amount)}. Shared vault backing is not personal inventory. Reduce the amount.`, cargo.player);
     if (backing < options.amount)
         failWalletCargo(`Shared Game vault backing ${String(backing)} is below requested ${String(options.amount)}. Retry after backing is restored.`, source);
-    if (config.cargo.withdrawEpochDuration === 0)
+    if (cargo.config.cargo.withdrawEpochDuration === 0)
         failWalletCargo('Withdrawal of this cargo is disabled by the Game configuration.', game);
-    if (options.amount > config.cargo.circuitBreaker)
-        failWalletCargo(`Requested amount exceeds the configured per-epoch withdrawal cap ${String(config.cargo.circuitBreaker)}. Reduce the amount.`, cache);
+    if (options.amount > cargo.config.cargo.circuitBreaker)
+        failWalletCargo(`Requested amount exceeds the configured per-epoch withdrawal cap ${String(cargo.config.cargo.circuitBreaker)}. Reduce the amount.`, cargo.cache);
     const preconditions = await Promise.all([
         [profileRaw, 'Profile authorization'],
         [characterRaw, 'Character identity'],
         [playerRaw, 'personal Starbase inventory'],
-        [systemRaw, 'System access configuration'],
-        [mintRaw, 'mint configuration'],
         ...(recipientRaw ? [[recipientRaw, 'wallet authority']] : []),
     ].map(([account, role]) => observeWalletAccount(account, role)));
-    preconditions.push({
-        kind: 'game-cargo-config',
-        address: game,
-        cargoId: options.cargoId,
-        configHash: config.configHash,
-        describes: 'The selected cargo configuration and cache identity remain unchanged; unrelated Game changes are allowed.',
-    }, {
-        kind: 'cargo-cache',
-        address: cache,
-        game,
-        bump,
-        describes: 'The canonical cargo cache retains valid Game identity and layout; counters may change.',
-    }, {
+    preconditions.push(systemGuard, ...walletCargoGuards(cargo, options.cargoId, game, decimals), {
         kind: 'token-account',
         address: source,
-        mint: config.cargo.mint,
-        owner: cache,
+        mint: cargo.mint,
+        owner: cargo.cache,
         minimumBalance: options.amount,
         describes: 'The existing shared vault remains a valid original Token account with sufficient raw tokens.',
     }, ...(destinationRaw
@@ -160,7 +76,7 @@ export async function planWithdrawCargoFromGame(ctx, starbase, options) {
             {
                 kind: 'token-account',
                 address: destination,
-                mint: config.cargo.mint,
+                mint: cargo.mint,
                 owner: options.recipient,
                 minimumBalance: 0n,
                 describes: 'The existing destination remains a valid original Token account; incoming tokens are allowed.',
@@ -169,9 +85,9 @@ export async function planWithdrawCargoFromGame(ctx, starbase, options) {
         : []));
     if (!recipientRaw)
         preconditions.push({
-            kind: 'account-absent',
+            kind: 'system-account-or-absent',
             address: options.recipient,
-            describes: 'The recipient authority account remains absent, preserving its observed non-multisig state.',
+            describes: 'The recipient wallet may remain absent or receive native funding as an empty, non-executable System account.',
         });
     const steps = [];
     if (!destinationRaw) {
@@ -179,83 +95,42 @@ export async function planWithdrawCargoFromGame(ctx, starbase, options) {
             failWalletCargo('The destination token account is missing. Create custom accounts separately or explicitly opt into canonical ATA creation with a payer.', destination);
         if (isOffCurveAddress(creation.payer))
             failWalletCargo('ATA creation payer must be a directly signing address.', creation.payer);
-        const extraAddresses = [
-            RENT_SYSVAR,
-            creation.payer,
-            ATA_PROGRAM,
-            SYSTEM_PROGRAM,
-            ORIGINAL_TOKEN_PROGRAM,
-        ];
-        const extraCandidates = await readContextRawAccounts(ctx, extraAddresses);
-        const extra = extraAddresses.map((address, index) => required(extraCandidates[index], address));
-        const [rent, payer, ...programs] = extra;
-        if (programs.some((program) => !program.executable))
-            failWalletCargo('Associated-token creation requires executable associated-token, System and original Token programs in this deployment.', ATA_PROGRAM);
-        if (rent.owner !== SYSVAR_OWNER ||
-            rent.executable ||
-            rent.data.length !== 17)
-            failWalletCargo('The deployment Rent sysvar has an unsupported owner or layout. Verify storage funding before creating an ATA.', RENT_SYSVAR);
-        const rentView = new DataView(rent.data.buffer, rent.data.byteOffset, rent.data.byteLength);
-        const rate = rentView.getBigUint64(0, true);
-        const threshold = rentView.getFloat64(8, true);
-        const rawCost = Number(rate * 293n) * threshold;
-        if (!Number.isFinite(rawCost) ||
-            rawCost < 0 ||
-            !Number.isSafeInteger(Math.floor(rawCost)))
-            failWalletCargo('ATA rent exemption cannot be represented exactly for this deployment.', RENT_SYSVAR);
-        const storageFunding = BigInt(Math.floor(rawCost));
-        if (payer.owner !== SYSTEM_PROGRAM ||
-            payer.executable ||
-            payer.data.length !== 0 ||
-            payer.lamports < storageFunding)
-            failWalletCargo(`ATA payer must be a System wallet with at least ${String(storageFunding)} lamports for storage, in addition to transaction fees.`, creation.payer);
-        preconditions.push(...(await Promise.all(extra.map((account, index) => observeWalletAccount(account, [
-            'Rent configuration',
-            'ATA payer identity',
-            'associated-token program',
-            'System program',
-            'Token program',
-        ][index])))), {
+        const ata = await resolveAssociatedTokenCreation(ctx, {
+            payer: creation.payer,
+            address: destination,
+            owner: options.recipient,
+            mint: cargo.mint,
+        }, failWalletCargo, observeWalletAccount);
+        preconditions.push(...ata.preconditions, {
             kind: 'token-account-or-absent',
             address: destination,
-            mint: config.cargo.mint,
+            mint: cargo.mint,
             owner: options.recipient,
             describes: 'The canonical recipient ATA is absent or a valid initialized unfrozen original Token account for this exact mint and recipient.',
         });
         steps.push({
-            describes: `Create the canonical recipient ATA ${destination} idempotently. Payer ${creation.payer} funds ${String(storageFunding)} lamports of rent-exempt storage if still absent; this is separate from transaction fees.`,
+            describes: `Create the canonical recipient ATA ${destination} idempotently. Payer ${creation.payer} funds ${String(ata.storageFunding)} lamports of rent-exempt storage if still absent; this is separate from transaction fees.`,
             signers: [creation.payer],
-            instruction: {
-                programAddress: ATA_PROGRAM,
-                accounts: [
-                    { address: creation.payer, role: AccountRole.WRITABLE_SIGNER },
-                    { address: destination, role: AccountRole.WRITABLE },
-                    { address: options.recipient, role: AccountRole.READONLY },
-                    { address: config.cargo.mint, role: AccountRole.READONLY },
-                    { address: SYSTEM_PROGRAM, role: AccountRole.READONLY },
-                    { address: ORIGINAL_TOKEN_PROGRAM, role: AccountRole.READONLY },
-                ],
-                data: new Uint8Array([1]),
-            },
+            instruction: ata.instruction,
         });
     }
     const epoch = cacheData.cargoTypeCache.get(options.cargoId);
-    const describes = `Withdraw ${String(options.amount)} raw token units of cargo ${String(options.cargoId)} from shared Game vault ${source} to ${destination}, owned by explicit recipient ${options.recipient}; debit the same verified zero-decimal quantity from player Starbase ${player}. Profile authority ${options.authorization.authority} signs; receiving does not require a recipient signature. Epoch duration ${String(config.cargo.withdrawEpochDuration)}, cap ${String(config.cargo.circuitBreaker)}; ${epoch ? `observed cache epoch ${String(epoch.currentEpoch)}, total withdrawn ${String(epoch.totalWithdrawn)}` : 'no retained cargo epoch entry'}. No remaining-epoch budget is predicted. Permissions, rollover, competing withdrawals and final balances remain chain-authoritative; simulate before signing. Transaction fees are paid separately by the execution fee payer.`;
+    const describes = `Withdraw ${String(options.amount)} raw token units of cargo ${String(options.cargoId)} from shared Game vault ${source} to ${destination}, owned by explicit recipient ${options.recipient}; debit the same verified zero-decimal quantity from player Starbase ${cargo.player}. Profile authority ${options.authorization.authority} signs; receiving does not require a recipient signature. Epoch duration ${String(cargo.config.cargo.withdrawEpochDuration)}, cap ${String(cargo.config.cargo.circuitBreaker)}; ${epoch ? `observed cache epoch ${String(epoch.currentEpoch)}, total withdrawn ${String(epoch.totalWithdrawn)}` : 'no retained cargo epoch entry'}. No remaining-epoch budget is predicted. Permissions, rollover, competing withdrawals and final balances remain chain-authoritative; simulate before signing. Transaction fees are paid separately by the execution fee payer. ${TOKEN_TRANSFER_DISCLOSURE}${recipientRaw ? '' : ' An absent recipient wallet may receive native funding as an empty, non-executable System account.'}`;
     steps.push({
         describes,
         signers: [options.authorization.authority],
         instruction: adaptWithdrawCargoFromGameInstruction({
             authorization: options.authorization,
-            systemAndStarbasePlayerSystem: starbase.system.address,
-            systemAndStarbasePlayerStarbasePlayer: player,
+            systemAndStarbasePlayerSystem: cargo.system,
+            systemAndStarbasePlayerStarbasePlayer: cargo.player,
             game,
-            cargoCache: cache,
+            cargoCache: cargo.cache,
             source,
             destination,
             amount: options.amount,
         }),
     });
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'cargo.wallet-withdrawal',
         summary: describes,
         preconditions,