movehat 0.1.2 → 0.1.4

package/README.md

@@ -7,12 +7,14 @@
 
 ## Features
 
-- **Auto-detection of Named Addresses** - Automatically detects and configures addresses from Move code (like Hardhat)
+- **Local Node Testing** - Run a real Movement blockchain locally for testing (just like Hardhat!)
+- **Dual Testing Modes** - Choose between `local-node` (full blockchain) or `fork` (read-only snapshot)
+- **Auto-Deploy in Tests** - Contracts deploy automatically when tests run - zero manual setup
+- **setupTestFixture Helper** - High-level API for test setup with type-safe contracts
+- **Auto-detection of Named Addresses** - Automatically detects and configures addresses from Move code
 - **Quick Start** - Scaffold new Move projects in seconds
 - **TypeScript Testing** - Write integration tests with familiar tools (Mocha, Chai)
-- **Built-in Helpers** - Interact with contracts easily
 - **Movement CLI Integration** - Seamless compilation and deployment
-- **Hot Reload** - Test changes instantly with watch mode
 
 ## Prerequisites
 
@@ -102,140 +104,217 @@ MH_NETWORK=testnet
 
 ## Writing Tests
 
-Movehat uses **Transaction Simulation** for testing - no real blockchain or gas costs required:
+Movehat runs tests on a **real local Movement blockchain** (just like Hardhat!):
 
 ```typescript
-import { describe, it, before } from "mocha";
+import { describe, it, before, after } from "mocha";
 import { expect } from "chai";
-import { getMovehat, type MovehatRuntime } from "movehat";
+import { setupTestFixture, teardownTestFixture, type TestFixture } from "movehat/helpers";
 
 describe("Counter Contract", () => {
-  let mh: MovehatRuntime;
-  let contractAddress: string;
+  let fixture: TestFixture<'counter'>;
 
   before(async function () {
-    this.timeout(30000);
+    this.timeout(60000); // Allow time for local node startup + deployment
+
+    // Setup local testing environment with auto-deployment
+    // This will:
+    // 1. Start a local Movement blockchain node
+    // 2. Generate and fund test accounts from local faucet
+    // 3. Auto-deploy the counter module
+    // 4. Return everything ready to use
+    fixture = await setupTestFixture(['counter'] as const, ['alice', 'bob']);
+
+    console.log(`\n✅ Testing on local blockchain`);
+    console.log(`   Deployer: ${fixture.accounts.deployer.accountAddress.toString()}`);
+  });
+
+  it("should initialize with value 0", async () => {
+    const counter = fixture.contracts.counter; // Type-safe, no `!` needed
+    const deployer = fixture.accounts.deployer;
+
+    // Read counter value (returns string from view function)
+    const value = await counter.view<string>("get", [
+      deployer.accountAddress.toString()
+    ]);
+
+    expect(parseInt(value)).to.equal(0);
+  });
 
-    // Initialize Movehat Runtime Environment
-    // Uses Movement testnet by default with auto-generated test accounts
-    mh = await getMovehat();
-    contractAddress = mh.account.accountAddress.toString();
+  it("should increment counter", async () => {
+    const counter = fixture.contracts.counter;
+    const deployer = fixture.accounts.deployer;
+
+    // Increment the counter (real transaction on local blockchain!)
+    const tx = await counter.call(deployer, "increment", []);
+    console.log(`   Transaction: ${tx.hash}`);
+
+    // Read new value
+    const value = await counter.view<string>("get", [
+      deployer.accountAddress.toString()
+    ]);
+
+    expect(parseInt(value)).to.equal(1);
   });
 
-  it("should initialize counter using simulation", async function () {
-    this.timeout(30000);
-
-    // Build transaction
-    const transaction = await mh.aptos.transaction.build.simple({
-      sender: mh.account.accountAddress,
-      data: {
-        function: `${contractAddress}::counter::init`,
-        functionArguments: []
-      }
-    });
-
-    // Simulate transaction (no gas cost, instant)
-    const [simulation] = await mh.aptos.transaction.simulate.simple({
-      signerPublicKey: mh.account.publicKey,
-      transaction
-    });
-
-    // Verify simulation succeeded
-    expect(simulation.success).to.be.true;
-    console.log(`Gas used: ${simulation.gas_used}`);
+  after(async () => {
+    // Cleanup: Stop local node and clear account pool
+    await teardownTestFixture();
   });
 });
 ```
 
-**Benefits of Transaction Simulation:**
-- No blockchain or fork server required
-- Instant test execution
-- No gas costs
-- Perfect for TDD and CI/CD
-- Uses Movement testnet with auto-generated accounts by default
+**Benefits of Local Node Testing:**
+- Real blockchain with actual state changes
+- Test real transactions (not just simulations)
+- Auto-deploy contracts for each test run
+- Type-safe contract access (no `!` operator needed)
+- Automatic cleanup after tests
+- Just like Hardhat - zero manual setup
 
 ## Writing Deployment Scripts
 
 ```typescript
-import { setupTestEnvironment, getContract } from "movehat/helpers";
+import { getMovehat } from "movehat";
 
 async function main() {
-  console.log("Deploying Counter contract...\n");
-
-  const env = await setupTestEnvironment();
-  
-  const counter = getContract(
-    env.aptos,
-    env.account.accountAddress.toString(),
-    "counter"
-  );
-
-  console.log(`Contract address: ${env.account.accountAddress.toString()}::counter`);
-  
+  const mh = await getMovehat();
+
+  console.log("Deploying from:", mh.account.accountAddress.toString());
+  console.log("Network:", mh.config.network);
+
+  // Deploy (publish) the module
+  // Movehat automatically checks if already deployed
+  const deployment = await mh.deployContract("counter");
+
+  console.log("Module deployed at:", deployment.address);
+  console.log("Transaction:", deployment.txHash);
+
+  // Get contract instance
+  const contract = mh.getContract(deployment.address, "counter");
+
   // Initialize the counter
-  console.log("\nInitializing counter...");
-  const txResult = await counter.call(env.account, "init", []);
-  
-  console.log(`Transaction hash: ${txResult.hash}`);
-  console.log(`Counter initialized successfully!`);
-  
+  await contract.call(mh.account, "init", []);
+
+  console.log("Counter initialized!");
+
   // Verify
-  const value = await counter.view<number>("get", [
-    env.account.accountAddress.toString()
+  const value = await contract.view<string>("get", [
+    mh.account.accountAddress.toString()
   ]);
-  
+
   console.log(`Initial counter value: ${value}`);
 }
 
 main().catch((error) => {
-  console.error("Deployment failed:", error);
+  console.error(error);
   process.exit(1);
 });
 ```
 
 ## API Reference
 
-### Helpers
+### Testing Helpers
 
-#### `setupTestEnvironment()`
+#### `setupTestFixture(modules, accountLabels, options?)`
 
-Sets up the test environment with Aptos client and account.
+High-level API for setting up local testing with auto-deployment. Returns type-safe fixture with contracts and accounts.
 
 ```typescript
-const env = await setupTestEnvironment();
-// Returns: { aptos: Aptos, account: Account, config: MovehatConfig }
+// Setup with type inference
+const fixture = await setupTestFixture(
+  ['counter'] as const,  // Modules to deploy
+  ['alice', 'bob']       // Additional account labels
+);
+
+// Access type-safe contracts (no `!` needed)
+const counter = fixture.contracts.counter;
+
+// Access accounts
+const deployer = fixture.accounts.deployer;
+const alice = fixture.accounts.alice;
+
+// Options (all optional)
+const fixture = await setupTestFixture(['counter'] as const, ['alice'], {
+  mode: 'fork',                    // 'local-node' (default) or 'fork'
+  defaultBalance: 100_000_000,     // Balance per account in octas
+  nodeForceRestart: true,          // Restart node on each run
+  // ... see LocalTestOptions for more
+});
 ```
 
-#### `getContract(aptos, moduleAddress, moduleName)`
+#### `setupLocalTesting(options?)`
 
-Creates a contract wrapper for easy interaction.
+Lower-level API for setting up local testing environment. Returns MovehatRuntime.
+
+```typescript
+import { setupLocalTesting } from "movehat/helpers";
+
+// Local node mode (default) - Full blockchain
+const mh = await setupLocalTesting({
+  mode: 'local-node',
+  accountLabels: ['deployer', 'alice', 'bob'],
+  autoDeploy: ['counter'],  // Auto-deploy modules
+  autoFund: true,
+  defaultBalance: 100_000_000
+});
+
+// Fork mode - Read-only snapshot
+const mh = await setupLocalTesting({
+  mode: 'fork',
+  forkNetwork: 'testnet',
+  forkName: 'my-fork',
+  accountLabels: ['alice', 'bob'],
+  // Note: autoDeploy doesn't work in fork mode
+});
+```
+
+#### `teardownTestFixture()`
+
+Cleanup function to stop local node and clear accounts.
 
 ```typescript
-const counter = getContract(aptos, accountAddress, "counter");
+after(async () => {
+  await teardownTestFixture();
+});
 ```
 
-#### `contract.call(signer, functionName, args, typeArgs)`
+#### `stopLocalTesting()`
 
-Executes an entry function (transaction).
+Stops the local testing environment (for lower-level API).
 
 ```typescript
-const tx = await counter.call(account, "increment", []);
+await stopLocalTesting();
 ```
 
-#### `contract.view(functionName, args, typeArgs)`
+### Contract Interaction
 
-Reads data from a view function (no transaction).
+#### `mh.getContract(moduleAddress, moduleName)`
+
+Creates a contract wrapper for easy interaction.
+
+```typescript
+const mh = await getMovehat();
+const counter = mh.getContract(deployment.address, "counter");
+```
+
+#### `contract.call(signer, functionName, args, typeArgs?)`
+
+Executes an entry function (transaction).
 
 ```typescript
-const value = await counter.view<number>("get", [address]);
+const tx = await counter.call(account, "increment", []);
+console.log(`Transaction: ${tx.hash}`);
 ```
 
-#### `assertTransactionSuccess(result)`
+#### `contract.view<T>(functionName, args, typeArgs?)`
 
-Asserts that a transaction was successful.
+Reads data from a view function (no transaction).
 
 ```typescript
-assertTransactionSuccess(txResult);
+// Note: View functions return strings
+const value = await counter.view<string>("get", [address]);
+console.log(`Value: ${parseInt(value)}`);
 ```
 
 ## Available Commands

package/bin/movehat.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+// Suppress experimental JSON module warning
+process.removeAllListeners('warning');
+process.on('warning', (warning) => {
+  if (warning.name === 'ExperimentalWarning' &&
+      warning.message.includes('Importing JSON modules')) {
+    return;
+  }
+  console.warn(warning);
+});
+
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 

package/dist/commands/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAKA,wBAA8B,UAAU,CAAC,UAAU,EAAE,MAAM,iBAqD1D"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAMA,wBAA8B,UAAU,CAAC,UAAU,EAAE,MAAM,iBA4F1D"}

package/dist/commands/run.js

@@ -2,6 +2,7 @@ import { spawn } from "child_process";
 import { resolve, extname, dirname, join } from "path";
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 export default async function runCommand(scriptPath) {
     if (!scriptPath) {
         console.error("❌ Error: No script path provided");
@@ -28,12 +29,48 @@ export default async function runCommand(scriptPath) {
         console.log(`   Network: ${network}`);
     }
     console.log();
-    // Find tsx from movehat's node_modules
+    // Find tsx binary - try multiple locations for compatibility
+    // Uses require.resolve for cross-platform compatibility (works on Windows, macOS, Linux)
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
-    const tsxPath = join(__dirname, "..", "..", "node_modules", ".bin", "tsx");
+    // Create require function for ESM (needed to use require.resolve in ESM modules)
+    const require = createRequire(import.meta.url);
+    let tsxPath;
+    try {
+        // Try to resolve tsx package from user's project first
+        const tsxPackagePath = require.resolve("tsx", { paths: [process.cwd()] });
+        // require.resolve("tsx") returns .../tsx/dist/loader.mjs
+        // We need to go up to the tsx package root, then into dist/cli.mjs
+        const tsxPackageRoot = dirname(dirname(tsxPackagePath));
+        tsxPath = join(tsxPackageRoot, "dist", "cli.mjs");
+        // Verify the file exists
+        if (!existsSync(tsxPath)) {
+            throw new Error("cli.mjs not found");
+        }
+    }
+    catch {
+        try {
+            // Fallback to movehat's own tsx
+            const tsxPackagePath = require.resolve("tsx", { paths: [__dirname] });
+            const tsxPackageRoot = dirname(dirname(tsxPackagePath));
+            tsxPath = join(tsxPackageRoot, "dist", "cli.mjs");
+            if (!existsSync(tsxPath)) {
+                throw new Error("cli.mjs not found");
+            }
+        }
+        catch {
+            tsxPath = "";
+        }
+    }
+    if (!tsxPath) {
+        console.error("❌ Error: tsx binary not found");
+        console.error("   Make sure 'tsx' is installed in your project:");
+        console.error("   npm install --save-dev tsx");
+        process.exit(1);
+    }
     // Execute script with tsx (handles both .ts and .js files)
-    const child = spawn(tsxPath, [fullPath], {
+    // Using 'node' to execute tsx for cross-platform compatibility
+    const child = spawn("node", [tsxPath, fullPath], {
         stdio: "inherit",
         env: {
             ...process.env,

package/dist/commands/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,UAAU,CAAC,UAAkB;IACzD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QAClD,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACrE,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAC;QAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;IAEpD,uBAAuB;IACvB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,KAAK,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,KAAK,CAAC,4BAA4B,GAAG,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,sBAAsB,UAAU,EAAE,CAAC,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;IAEd,uCAAuC;IACvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE3E,2DAA2D;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE;QACvC,KAAK,EAAE,SAAS;QAChB,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,gDAAgD;SACjD;KACF,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC1B,OAAO,CAAC,KAAK,CAAC,+BAA+B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"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"}

package/dist/core/AccountManager.d.ts

@@ -0,0 +1,186 @@
+import { Account } from "@aptos-labs/ts-sdk";
+import { MovehatConfig } from "../types/config.js";
+/**
+ * Represents a stored account in the pool
+ */
+export interface StoredAccount {
+    label?: string;
+    privateKey: string;
+    address: string;
+    createdAt: number;
+}
+/**
+ * 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.
+ */
+export declare class AccountManager {
+    private static pool;
+    private static privateKeys;
+    private static labelMap;
+    private static poolLoaded;
+    private static defaultPoolPath;
+    /**
+     * 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")
+     * @returns An Account instance
+     *
+     * @example
+     * const alice = AccountManager.getTestAccount("alice");
+     * const randomAccount = AccountManager.getTestAccount();
+     */
+    static getTestAccount(label?: string): Account;
+    /**
+     * 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);
+     */
+    static createAccount(label?: string, fund?: boolean): 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()}`);
+     * }
+     */
+    static getAccountByLabel(label: string): Account | undefined;
+    /**
+     * 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
+     *
+     * @example
+     * const account = AccountManager.loadAccountFromEnv("MH_PRIVATE_KEY");
+     */
+    static loadAccountFromEnv(envVar?: string): Account;
+    /**
+     * 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...");
+     */
+    static loadAccountFromPrivateKey(privateKeyHex: string): 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);
+     */
+    static loadAccountsFromConfig(config: MovehatConfig): Account[];
+    /**
+     * 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()}`);
+     */
+    static getLabeledAccounts(): Record<string, Account>;
+    /**
+     * Save the current account pool to disk for persistence
+     *
+     * @param poolPath Optional custom path (defaults to .movehat/accounts)
+     *
+     * @example
+     * AccountManager.saveAccountPool();
+     */
+    static saveAccountPool(poolPath?: string): void;
+    /**
+     * 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");
+     * }
+     */
+    static loadAccountPool(poolPath?: string): boolean;
+    /**
+     * Clear the entire account pool
+     * Useful for test isolation
+     *
+     * @example
+     * after(() => {
+     *   AccountManager.clearPool();
+     * });
+     */
+    static clearPool(): void;
+    /**
+     * Get the current size of the account pool
+     *
+     * @returns Number of accounts in the pool
+     */
+    static getPoolSize(): number;
+    /**
+     * Get all accounts in the pool
+     *
+     * @returns Array of all Account instances
+     */
+    static getAllAccounts(): Account[];
+    /**
+     * Check if a label is already in use
+     *
+     * @param label The label to check
+     * @returns true if label exists, false otherwise
+     */
+    static hasLabel(label: string): boolean;
+    /**
+     * 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
+     */
+    static getOrCreateLabeled(label: string): Account;
+    /**
+     * 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());
+     */
+    static createBatch(labels: readonly string[]): Record<string, Account>;
+    /**
+     * 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
+     */
+    static exportPrivateKeys(labels?: string[]): Record<string, string>;
+}
+//# sourceMappingURL=AccountManager.d.ts.map

package/dist/core/AccountManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountManager.d.ts","sourceRoot":"","sources":["../../src/core/AccountManager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAER,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAmC;IACtD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAkC;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IACzD,OAAO,CAAC,MAAM,CAAC,UAAU,CAAS;IAClC,OAAO,CAAC,MAAM,CAAC,eAAe,CAA+C;IAE7E;;;;;;;;;;OAUG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO;IAa9C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,OAAe,GAAG,OAAO;IAkBpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAQ5D;;;;;;;;;OASG;IACH,MAAM,CAAC,kBAAkB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO;IAalE;;;;;;;;OAQG;IACH,MAAM,CAAC,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;IAchE;;;;;;;;;OASG;IACH,MAAM,CAAC,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,EAAE;IAiB/D;;;;;;;;OAQG;IACH,MAAM,CAAC,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAapD;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IA+C/C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAgDlD;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,IAAI,IAAI;IAOxB;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM;IAI5B;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,OAAO,EAAE;IAIlC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAQjD;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUtE;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CA0BpE"}