movehat 0.2.6 → 0.2.8

package/dist/core/AccountManager.js

@@ -1,59 +1,82 @@
 import { Account, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants, } from "@aptos-labs/ts-sdk";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import { logger } from "../ui/index.js";
 /**
  * Centralized Account Manager for movehat
  *
  * Manages all account creation, loading, and lifecycle operations.
- * Provides a pool of reusable test accounts with labels for better test readability.
+ * Provides a pool of reusable test accounts with labels for better test
+ * readability.
+ *
+ * Two API surfaces are exposed:
+ *
+ * **Instance API (recommended; M9.1+)** — `new AccountManager(options?)`
+ * gives a fully isolated pool. Two instances in the same process have
+ * independent labelMaps, private-key maps, and account pools. Each
+ * `Harness` constructed in 0.3.0+ will own one of these; user code
+ * accesses labeled accounts via `harness.accounts.<label>` (Harness
+ * snapshots them at construction time).
+ *
+ * **Static facade (deprecated; will be removed in 0.3.0)** — every
+ * former static method (`AccountManager.createAccount(...)`, etc.) still
+ * works and forwards to a single process-wide singleton. This preserves
+ * the existing label-sharing behavior across calls during the
+ * deprecation window. Migration target is the instance API; see M9 meta
+ * (#270) and migration guide at `/docs/upgrading/0.3.0` (published in
+ * M9.4).
  */
 export class AccountManager {
-    // Class-static maps: shared across every consumer in the same Node
-    // process (e.g. two Harness instances). Re-using a label across
-    // "sessions" overwrites the labelMap entry. Documented + fixed by
-    // contract in `AccountManager.global-state.test.ts` (audit F8).
-    static pool = new Map(); // address → Account
-    static privateKeys = new Map(); // address → privateKey hex
-    static labelMap = new Map(); // label → address
-    static generatedAccountAddresses = new Set();
-    static poolLoaded = false;
-    // `defaultPoolPath` is captured ONCE at module-import time. A later
-    // `process.chdir(...)` does NOT redirect the save destination — pass
-    // an explicit `poolPath` to `saveAccountPool`/`loadAccountPool` when
-    // per-test isolation matters. See audit finding F8.
-    static defaultPoolPath = join(process.cwd(), ".movehat", "accounts");
+    // ── Instance state ──────────────────────────────────────────────
+    // All former class-static fields are now instance fields. Two
+    // `new AccountManager()` calls produce fully isolated state. The
+    // static facade below operates on a single module-level singleton,
+    // so existing callers see no behavior change.
+    pool = new Map(); // address → Account
+    privateKeys = new Map(); // address → privateKey hex
+    labelMap = new Map(); // label → address
+    generatedAccountAddresses = new Set();
+    poolLoaded = false;
+    poolPathOverride;
+    constructor(options = {}) {
+        this.poolPathOverride = options.poolPath;
+    }
     /**
-     * Get a test account from the pool. If label is provided and exists, returns that account.
-     * Otherwise creates a new account with the optional label.
+     * Resolved pool directory. When the caller supplied an explicit
+     * `poolPath` to the constructor, that value is returned verbatim.
+     * Otherwise the path is computed LAZILY from the current
+     * `process.cwd()` on each access — so `process.chdir()` performed
+     * between construction and pool I/O takes effect, unlike the legacy
+     * static-only API which captured cwd at module import time
+     * (audit finding F8(b)).
+     */
+    get poolPath() {
+        return this.poolPathOverride ?? join(process.cwd(), ".movehat", "accounts");
+    }
+    // ── Instance methods (real implementations) ─────────────────────
+    /**
+     * Get a test account from the pool. If label is provided and exists,
+     * returns that account. Otherwise creates a new account with the
+     * optional label.
      *
-     * @param label Optional label for the account (e.g., "alice", "bob", "deployer")
+     * @param label Optional label for the account (e.g., "alice", "bob")
      * @returns An Account instance
-     *
-     * @example
-     * const alice = AccountManager.getTestAccount("alice");
-     * const randomAccount = AccountManager.getTestAccount();
      */
-    static getTestAccount(label) {
+    getTestAccount(label) {
         if (label) {
-            const existingAccount = this.getAccountByLabel(label);
-            if (existingAccount) {
-                return existingAccount;
+            const existing = this.getAccountByLabel(label);
+            if (existing) {
+                return existing;
             }
         }
         return this.createAccount(label, false);
     }
     /**
-     * Create a new account and optionally add it to the pool with a label
-     *
-     * @param label Optional label for the account
-     * @param fund Whether to fund the account (handled externally)
-     * @returns A new Account instance
-     *
-     * @example
-     * const deployer = AccountManager.createAccount("deployer");
-     * const bob = AccountManager.createAccount("bob", true);
+     * Create a new account and optionally add it to the pool with a
+     * label. The `fund` parameter is accepted for API symmetry; actual
+     * funding is the caller's responsibility.
      */
-    static createAccount(label, fund = false) {
+    createAccount(label, _fund = false) {
         const account = Account.generate();
         const address = account.accountAddress.toString();
         this.pool.set(address, account);
@@ -65,18 +88,9 @@ export class AccountManager {
         return account;
     }
     /**
-     * Get an account by its label
-     *
-     * @param label The label to look up
-     * @returns The Account if found, undefined otherwise
-     *
-     * @example
-     * const alice = AccountManager.getAccountByLabel("alice");
-     * if (alice) {
-     *   console.log(`Alice's address: ${alice.accountAddress.toString()}`);
-     * }
+     * Get an account by its label, or undefined if not present.
      */
-    static getAccountByLabel(label) {
+    getAccountByLabel(label) {
         const address = this.labelMap.get(label);
         if (!address) {
             return undefined;
@@ -84,16 +98,11 @@ export class AccountManager {
         return this.pool.get(address);
     }
     /**
-     * Load account from environment variable
-     *
-     * @param envVar The environment variable name (defaults to "PRIVATE_KEY")
-     * @returns Account instance
-     * @throws Error if environment variable is not set
+     * Load account from environment variable.
      *
-     * @example
-     * const account = AccountManager.loadAccountFromEnv("MH_PRIVATE_KEY");
+     * @throws Error if the environment variable is not set
      */
-    static loadAccountFromEnv(envVar = "PRIVATE_KEY") {
+    loadAccountFromEnv(envVar = "PRIVATE_KEY") {
         const privateKeyHex = process.env[envVar];
         if (!privateKeyHex) {
             throw new Error(`Environment variable ${envVar} not found. ` +
@@ -102,15 +111,9 @@ export class AccountManager {
         return this.loadAccountFromPrivateKey(privateKeyHex);
     }
     /**
-     * Load account from a private key hex string
-     *
-     * @param privateKeyHex The private key as a hex string (with or without 0x prefix)
-     * @returns Account instance
-     *
-     * @example
-     * const account = AccountManager.loadAccountFromPrivateKey("0xabc123...");
+     * Load account from a private key hex string (with or without 0x prefix).
      */
-    static loadAccountFromPrivateKey(privateKeyHex) {
+    loadAccountFromPrivateKey(privateKeyHex) {
         // Format into AIP-80 shape (`ed25519-priv-0x…`) before constructing
         // the SDK type. Without this, raw-hex inputs trigger a noisy
         // deprecation warning from `@aptos-labs/ts-sdk` on every call.
@@ -119,16 +122,9 @@ export class AccountManager {
         return account;
     }
     /**
-     * Load all accounts from movehat config
-     *
-     * @param config The resolved MovehatConfig
-     * @returns Array of Account instances
-     *
-     * @example
-     * const config = await resolveNetworkConfig(userConfig);
-     * const accounts = AccountManager.loadAccountsFromConfig(config);
+     * Load all accounts from movehat config.
      */
-    static loadAccountsFromConfig(config) {
+    loadAccountsFromConfig(config) {
         const accounts = [];
         for (const privateKeyHex of config.allAccounts) {
             try {
@@ -137,21 +133,15 @@ export class AccountManager {
             }
             catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                console.warn(`Warning: Failed to load account from config: ${msg}`);
+                logger.warning(`Failed to load account from config: ${msg}`);
             }
         }
         return accounts;
     }
     /**
-     * Get all labeled accounts in the pool
-     *
-     * @returns Record of label to Account mappings
-     *
-     * @example
-     * const labeled = AccountManager.getLabeledAccounts();
-     * console.log(`Deployer: ${labeled.deployer?.accountAddress.toString()}`);
+     * Get all labeled accounts in the pool.
      */
-    static getLabeledAccounts() {
+    getLabeledAccounts() {
         const result = {};
         for (const [label, address] of this.labelMap.entries()) {
             const account = this.pool.get(address);
@@ -161,25 +151,25 @@ export class AccountManager {
         }
         return result;
     }
-    static saveAccountPool(poolPathOrOptions, options = {}) {
-        const poolPath = typeof poolPathOrOptions === "string" ? poolPathOrOptions : undefined;
+    saveAccountPool(poolPathOrOptions, options = {}) {
+        const explicitPath = typeof poolPathOrOptions === "string" ? poolPathOrOptions : undefined;
         const effectiveOptions = typeof poolPathOrOptions === "object" && poolPathOrOptions !== null
             ? poolPathOrOptions
             : options;
         const includeImported = effectiveOptions.includeImported ?? false;
-        const basePath = poolPath || this.defaultPoolPath;
+        const basePath = explicitPath || this.poolPath;
         // Ensure directory exists with restrictive perms (the pool file holds
         // plaintext private keys, so the directory must not be world-readable).
-        // Note: mkdirSync's mode is masked by the process umask, so we chmod
-        // explicitly afterwards to guarantee 0o700 regardless of umask.
+        // mkdirSync's mode is masked by the process umask; chmod explicitly
+        // afterwards to guarantee 0o700.
         if (!existsSync(basePath)) {
             mkdirSync(basePath, { recursive: true, mode: 0o700 });
         }
         chmodSync(basePath, 0o700);
-        // Build stored accounts array
         const storedAccounts = [];
         const labelMapObject = {};
         for (const [address, account] of this.pool.entries()) {
+            void account;
             if (!includeImported && !this.generatedAccountAddresses.has(address)) {
                 continue;
             }
@@ -194,7 +184,7 @@ export class AccountManager {
             }
             const privateKey = this.privateKeys.get(address);
             if (!privateKey) {
-                console.warn(`Warning: No private key found for account ${address}, skipping`);
+                logger.warning(`No private key found for account ${address}, skipping`);
                 continue;
             }
             storedAccounts.push({
@@ -208,10 +198,6 @@ export class AccountManager {
             accounts: storedAccounts,
             labelMap: labelMapObject,
         };
-        // Write to file with owner-only permissions — file contains plaintext
-        // private keys for test accounts. writeFileSync's mode is masked by
-        // the process umask, so we chmod explicitly afterwards to guarantee
-        // 0o600 regardless of umask.
         const poolFilePath = join(basePath, "test-pool.json");
         writeFileSync(poolFilePath, JSON.stringify(poolData, null, 2), {
             encoding: "utf-8",
@@ -220,31 +206,22 @@ export class AccountManager {
         chmodSync(poolFilePath, 0o600);
     }
     /**
-     * Load account pool from disk
-     *
-     * @param poolPath Optional custom path (defaults to .movehat/accounts)
-     * @returns true if pool was loaded, false if file doesn't exist
-     *
-     * @example
-     * if (AccountManager.loadAccountPool()) {
-     *   console.log("Pool loaded successfully");
-     * }
+     * Load account pool from disk. Returns true if a pool file was found
+     * and parsed, false if the file does not exist or parsing failed.
      */
-    static loadAccountPool(poolPath) {
+    loadAccountPool(poolPath) {
         if (this.poolLoaded) {
-            return true; // Already loaded
+            return true;
         }
-        const basePath = poolPath || this.defaultPoolPath;
+        const basePath = poolPath || this.poolPath;
         const poolFilePath = join(basePath, "test-pool.json");
         if (!existsSync(poolFilePath)) {
             return false;
         }
         try {
             const poolData = JSON.parse(readFileSync(poolFilePath, "utf-8"));
-            // Clear existing pool
             this.pool.clear();
             this.labelMap.clear();
-            // Restore accounts
             for (const stored of poolData.accounts) {
                 const account = this.accountFromPrivateKey(stored.privateKey);
                 this.trackAccount(account, stored.privateKey, "generated");
@@ -263,20 +240,14 @@ export class AccountManager {
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            console.warn(`Warning: Failed to load account pool: ${msg}`);
+            logger.warning(`Failed to load account pool: ${msg}`);
             return false;
         }
     }
     /**
-     * Clear the entire account pool
-     * Useful for test isolation
-     *
-     * @example
-     * after(() => {
-     *   AccountManager.clearPool();
-     * });
+     * Clear the entire account pool. Useful for test isolation.
      */
-    static clearPool() {
+    clearPool() {
         this.pool.clear();
         this.privateKeys.clear();
         this.labelMap.clear();
@@ -284,43 +255,27 @@ export class AccountManager {
         this.poolLoaded = false;
     }
     /**
-     * Get the current size of the account pool
-     *
-     * @returns Number of accounts in the pool
+     * Number of accounts in the pool.
      */
-    static getPoolSize() {
+    getPoolSize() {
         return this.pool.size;
     }
     /**
-     * Get all accounts in the pool
-     *
-     * @returns Array of all Account instances
+     * All accounts in the pool.
      */
-    static getAllAccounts() {
+    getAllAccounts() {
         return Array.from(this.pool.values());
     }
     /**
-     * Check if a label is already in use
-     *
-     * @param label The label to check
-     * @returns true if label exists, false otherwise
+     * Whether a label is currently bound to an account in this pool.
      */
-    static hasLabel(label) {
+    hasLabel(label) {
         return this.labelMap.has(label);
     }
     /**
-     * Get or create an account with a specific label
-     * If the label exists, returns the existing account
-     * Otherwise creates a new account with that label
-     *
-     * @param label The label for the account
-     * @returns Account instance
-     *
-     * @example
-     * const alice = AccountManager.getOrCreateLabeled("alice");
-     * const aliceAgain = AccountManager.getOrCreateLabeled("alice"); // Same account
+     * Get or create an account with a specific label.
      */
-    static getOrCreateLabeled(label) {
+    getOrCreateLabeled(label) {
         const existing = this.getAccountByLabel(label);
         if (existing) {
             return existing;
@@ -328,16 +283,9 @@ export class AccountManager {
         return this.createAccount(label, false);
     }
     /**
-     * Batch create multiple labeled accounts
-     *
-     * @param labels Array of labels to create
-     * @returns Record of label to Account mappings
-     *
-     * @example
-     * const accounts = AccountManager.createBatch(["alice", "bob", "charlie"]);
-     * console.log(accounts.alice.accountAddress.toString());
+     * Batch create multiple labeled accounts.
      */
-    static createBatch(labels) {
+    createBatch(labels) {
         const result = {};
         for (const label of labels) {
             result[label] = this.getOrCreateLabeled(label);
@@ -345,16 +293,12 @@ export class AccountManager {
         return result;
     }
     /**
-     * Export account private keys for backup/sharing
-     * WARNING: Only use this for test accounts, never production keys
-     *
-     * @param labels Optional array of labels to export (exports all if not provided)
-     * @returns Record of label/address to private key hex string
+     * Export account private keys for backup/sharing.
+     * WARNING: Only use this for test accounts, never production keys.
      */
-    static exportPrivateKeys(labels) {
+    exportPrivateKeys(labels) {
         const result = {};
         if (labels) {
-            // Export specific labels
             for (const label of labels) {
                 const address = this.labelMap.get(label);
                 if (address) {
@@ -366,7 +310,6 @@ export class AccountManager {
             }
         }
         else {
-            // Export all labeled accounts
             for (const [label, address] of this.labelMap.entries()) {
                 const privateKey = this.privateKeys.get(address);
                 if (privateKey) {
@@ -376,12 +319,12 @@ export class AccountManager {
         }
         return result;
     }
-    static accountFromPrivateKey(privateKeyHex) {
+    accountFromPrivateKey(privateKeyHex) {
         const formatted = PrivateKey.formatPrivateKey(privateKeyHex, PrivateKeyVariants.Ed25519);
         const privateKey = new Ed25519PrivateKey(formatted);
         return Account.fromPrivateKey({ privateKey });
     }
-    static trackAccount(account, privateKeyHex, source) {
+    trackAccount(account, privateKeyHex, source) {
         const address = account.accountAddress.toString();
         this.pool.set(address, account);
         this.privateKeys.set(address, privateKeyHex);
@@ -392,4 +335,120 @@ export class AccountManager {
             this.generatedAccountAddresses.delete(address);
         }
     }
+    // ── Static facade (deprecated; removed in 0.3.0) ────────────────
+    //
+    // Every former static method below forwards to `__defaultManager`,
+    // a module-level singleton constructed once at import time. This
+    // preserves the legacy "process-wide pool shared across consumers"
+    // behavior so existing callers see no change during the 0.2.7
+    // deprecation window. The singleton is constructed with its
+    // `poolPath` eagerly captured from the import-time `process.cwd()`
+    // — preserving F8(b) for the static API specifically.
+    //
+    // Removal happens in M9.4 (0.3.0). Until then the runtime warning
+    // added in M9.3 nudges users toward `harness.accounts.<label>` or
+    // `harness.runtime.accountManager.*`.
+    static getTestAccount(label) {
+        __warnDeprecated("getTestAccount");
+        return __defaultManager.getTestAccount(label);
+    }
+    static createAccount(label, fund = false) {
+        __warnDeprecated("createAccount");
+        return __defaultManager.createAccount(label, fund);
+    }
+    static getAccountByLabel(label) {
+        __warnDeprecated("getAccountByLabel");
+        return __defaultManager.getAccountByLabel(label);
+    }
+    static loadAccountFromEnv(envVar = "PRIVATE_KEY") {
+        __warnDeprecated("loadAccountFromEnv");
+        return __defaultManager.loadAccountFromEnv(envVar);
+    }
+    static loadAccountFromPrivateKey(privateKeyHex) {
+        __warnDeprecated("loadAccountFromPrivateKey");
+        return __defaultManager.loadAccountFromPrivateKey(privateKeyHex);
+    }
+    static loadAccountsFromConfig(config) {
+        __warnDeprecated("loadAccountsFromConfig");
+        return __defaultManager.loadAccountsFromConfig(config);
+    }
+    static getLabeledAccounts() {
+        __warnDeprecated("getLabeledAccounts");
+        return __defaultManager.getLabeledAccounts();
+    }
+    static saveAccountPool(poolPathOrOptions, options = {}) {
+        __warnDeprecated("saveAccountPool");
+        // Re-dispatch via the instance overloads, preserving caller intent.
+        if (poolPathOrOptions === undefined) {
+            __defaultManager.saveAccountPool();
+        }
+        else if (typeof poolPathOrOptions === "string") {
+            __defaultManager.saveAccountPool(poolPathOrOptions, options);
+        }
+        else {
+            __defaultManager.saveAccountPool(poolPathOrOptions);
+        }
+    }
+    static loadAccountPool(poolPath) {
+        __warnDeprecated("loadAccountPool");
+        return __defaultManager.loadAccountPool(poolPath);
+    }
+    static clearPool() {
+        __warnDeprecated("clearPool");
+        __defaultManager.clearPool();
+    }
+    static getPoolSize() {
+        __warnDeprecated("getPoolSize");
+        return __defaultManager.getPoolSize();
+    }
+    static getAllAccounts() {
+        __warnDeprecated("getAllAccounts");
+        return __defaultManager.getAllAccounts();
+    }
+    static hasLabel(label) {
+        __warnDeprecated("hasLabel");
+        return __defaultManager.hasLabel(label);
+    }
+    static getOrCreateLabeled(label) {
+        __warnDeprecated("getOrCreateLabeled");
+        return __defaultManager.getOrCreateLabeled(label);
+    }
+    static createBatch(labels) {
+        __warnDeprecated("createBatch");
+        return __defaultManager.createBatch(labels);
+    }
+    static exportPrivateKeys(labels) {
+        __warnDeprecated("exportPrivateKeys");
+        return __defaultManager.exportPrivateKeys(labels);
+    }
+}
+// Module-level singleton backing the static facade. The eager poolPath
+// capture mirrors the pre-M9 behavior — `process.chdir` after import
+// does NOT redirect static-facade pool I/O. F8(b) is preserved for
+// the static API and only flips for callers using the instance API.
+const __defaultManager = new AccountManager({
+    poolPath: join(process.cwd(), ".movehat", "accounts"),
+});
+// Once-per-method-per-process deprecation tracking for the static
+// facade. The warning fires on the FIRST call to each static method
+// per process, then stays silent for subsequent calls. A user with
+// 50 tests calling `AccountManager.getLabeledAccounts()` sees the
+// warning once, not 50 times.
+//
+// Exported as `_resetDeprecationWarnings` for tests that need to
+// verify warning behavior across multiple `it` blocks (vitest workers
+// share module state within a single test file).
+const __warnedMethods = new Set();
+/** @internal — test-only. Resets the once-per-method dedup Set. */
+export function _resetDeprecationWarnings() {
+    __warnedMethods.clear();
+}
+function __warnDeprecated(method) {
+    if (__warnedMethods.has(method))
+        return;
+    __warnedMethods.add(method);
+    logger.warning(`AccountManager.${method} is deprecated and will be removed in 0.3.0. ` +
+        `Use 'harness.accounts.<label>' for labeled-account access, or ` +
+        `'harness.runtime.accountManager.${method}' for direct manager calls. ` +
+        `See migration tracker: https://github.com/gilbertsahumada/movehat/issues/270`);
 }

package/dist/fork/api.d.ts

@@ -55,7 +55,7 @@ export declare class MovementApiClient {
     /**
      * Get a specific account resource
      */
-    getAccountResource(address: string, resourceType: string): Promise<any>;
+    getAccountResource(address: string, resourceType: string): Promise<AccountResource>;
     /**
      * Get all resources for an account
      */

package/dist/fork/api.js

@@ -2,6 +2,7 @@ import https from 'https';
 import http from 'http';
 import { URL } from 'url';
 import { normalizeAddressShort } from '../utils/address.js';
+import { assertLedgerInfo, assertAccountData, assertAccountResource, assertAccountResourceArray, } from './validation.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
 /**
@@ -191,14 +192,16 @@ export class MovementApiClient {
      * Get ledger information
      */
     async getLedgerInfo() {
-        return this.get(this.apiPath('/'));
+        const raw = await this.get(this.apiPath('/'));
+        return assertLedgerInfo(raw);
     }
     /**
      * Get account information
      */
     async getAccount(address) {
         const normalizedAddress = normalizeAddressShort(address);
-        return this.get(this.apiPath(`/accounts/${normalizedAddress}`));
+        const raw = await this.get(this.apiPath(`/accounts/${normalizedAddress}`));
+        return assertAccountData(raw);
     }
     /**
      * Get a specific account resource
@@ -207,14 +210,16 @@ export class MovementApiClient {
         const normalizedAddress = normalizeAddressShort(address);
         // URL encode the resource type
         const encodedType = encodeURIComponent(resourceType);
-        return this.get(this.apiPath(`/accounts/${normalizedAddress}/resource/${encodedType}`));
+        const raw = await this.get(this.apiPath(`/accounts/${normalizedAddress}/resource/${encodedType}`));
+        return assertAccountResource(raw);
     }
     /**
      * Get all resources for an account
      */
     async getAccountResources(address) {
         const normalizedAddress = normalizeAddressShort(address);
-        return this.get(this.apiPath(`/accounts/${normalizedAddress}/resources`));
+        const raw = await this.get(this.apiPath(`/accounts/${normalizedAddress}/resources`));
+        return assertAccountResourceArray(raw);
     }
     /**
      * Execute a Move view function via the upstream node's POST /v1/view.

package/dist/fork/manager.d.ts

@@ -36,8 +36,8 @@ export declare class ForkManager {
     load(): void;
     getMetadata(): ForkMetadata;
     getAccount(address: string): Promise<AccountState>;
-    getResource(address: string, resourceType: string): Promise<any>;
-    getAllResources(address: string): Promise<Record<string, any>>;
+    getResource(address: string, resourceType: string): Promise<unknown>;
+    getAllResources(address: string): Promise<Record<string, unknown>>;
     /**
      * Stateless passthrough of `POST /v1/view` to the upstream RPC.
      *

package/dist/fork/manager.js

@@ -3,6 +3,7 @@ import { MovementApiClient } from './api.js';
 import { ForkStorage } from './storage.js';
 import { normalizeAddress } from '../utils/address.js';
 import { logger } from '../ui/index.js';
+import { assertCoinStore } from './validation.js';
 /**
  * Derive a deterministic 32-byte hex placeholder for the `authentication_key`
  * of a fork-funded account. The real auth_key is `sha3_256(public_key || 0x00)`
@@ -182,17 +183,12 @@ export class ForkManager {
     async fundAccount(address, amount, coinType = '0x1::aptos_coin::AptosCoin') {
         const normalizedAddress = normalizeAddress(address);
         const resourceType = `0x1::coin::CoinStore<${coinType}>`;
-        // Try to get existing coin store. The coin store is a CoinStore<T>
-        // resource whose `data` is Movement-side untyped JSON; we shape it
-        // locally as a structural object with `coin.value: string`.
-        // any: full CoinStore schema lives at the Movement REST boundary —
-        // proper validation deferred to the boundary-validation follow-up of #57.
         let coinStore;
         try {
-            coinStore = await this.getResource(normalizedAddress, resourceType);
+            const raw = await this.getResource(normalizedAddress, resourceType);
+            coinStore = assertCoinStore(raw);
         }
         catch (error) {
-            // Only catch "not found" errors, rethrow others (network, API, etc.)
             const msg = error instanceof Error ? error.message : String(error);
             if (!msg.includes('not found')) {
                 throw error;
@@ -220,7 +216,7 @@ export class ForkManager {
                 frozen: false,
             };
         }
-        const currentBalance = BigInt(coinStore.coin.value ?? '0');
+        const currentBalance = BigInt(coinStore.coin.value);
         const newBalance = currentBalance + BigInt(amount);
         coinStore.coin.value = newBalance.toString();
         await this.setResource(normalizedAddress, resourceType, coinStore);