@hardkas/accounts 0.10.0-alpha → 0.11.0-alpha

package/dist/index.d.ts

@@ -396,4 +396,130 @@ declare function listDevAccountsSync(workspaceDir: string): {
     address: string;
 }[];
 
-export { type CreateKaspaWalletOptions, DEV_ACCOUNTS_PASSWORD, type EncryptedKeystoreV2, type EvmExportResult, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, HardkasFixtureSigner, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, appendToKeystoreJson, assertSigningNetworkAllowed, createEmptyRealAccountStore, createLocalKaspaWallet, describeAccount, ensureDevAccounts, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getOrCreateDevAccount, getRealDevAccount, getRequiredEnv, importRealDevAccount, listDevAccountsSync, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, prepareEvmAccountExport, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressNetwork, validateAddressPrefix, withKeystoreLock };
+type NetworkType = "simnet" | "testnet" | "mainnet" | "local-docker-simnet";
+type ChainType = "receive" | "change" | 0 | 1;
+interface PathRequest {
+    readonly accountIndex: number;
+    readonly chain: ChainType;
+    readonly addressIndex: number;
+}
+interface DeriveRequest {
+    readonly seedRef: string;
+    readonly accountIndex: number;
+    readonly chain: ChainType;
+    readonly addressIndex: number;
+    readonly network?: NetworkType;
+}
+interface DerivedAddress {
+    readonly address: string;
+    readonly path: string;
+    readonly network: NetworkType;
+    readonly derivationModel: "deterministic-simulated-v1";
+    readonly claims: {
+        readonly realBip39: false;
+        readonly productionCustody: false;
+    };
+}
+interface HelperDeriveRequest {
+    readonly seedRef: string;
+    readonly accountIndex: number;
+    readonly addressIndex: number;
+    readonly network?: NetworkType;
+}
+declare const AddressManager: {
+    path(opts: PathRequest): string;
+    derive(opts: DeriveRequest): DerivedAddress;
+    deriveReceive(opts: HelperDeriveRequest): DerivedAddress;
+    deriveChange(opts: HelperDeriveRequest): DerivedAddress;
+};
+
+interface WalletClaims {
+    readonly productionCustody: false;
+    readonly plaintextMnemonicStored: false;
+    readonly hardwareWallet: false;
+}
+interface WalletArtifact {
+    readonly schema: string;
+    readonly walletId: string;
+    readonly seedRef: string;
+    readonly keystoreRef: string;
+    readonly network: NetworkType;
+    readonly claims: WalletClaims;
+}
+interface WalletCreateRequest {
+    readonly walletId: string;
+    readonly network?: NetworkType;
+}
+interface WalletImportRequest {
+    readonly walletId: string;
+    readonly mnemonic: string;
+    readonly network?: NetworkType;
+}
+interface WalletMetadata {
+    readonly walletId: string;
+    readonly keystoreRef: string;
+    readonly network: NetworkType;
+    readonly createdAt: number;
+}
+declare class WalletManagerImpl {
+    private wallets;
+    private validateNetwork;
+    private generateSeedRef;
+    create(opts: WalletCreateRequest): WalletArtifact;
+    importMnemonic(opts: WalletImportRequest): WalletArtifact;
+    getSeedRef(walletId: string): string;
+    exportMetadata(walletId: string): WalletMetadata;
+}
+declare const WalletManager: WalletManagerImpl;
+
+interface WalletState {
+    walletId: string;
+    receiveIndex: number;
+    changeIndex: number;
+}
+interface WalletStateStoreOptions {
+    /**
+     * The path to the JSON file where state is stored.
+     * If not provided, it defaults to `.hardkas/wallet-state.json` in the current working directory.
+     */
+    filePath?: string;
+}
+/**
+ * A simple JSON-based state store for wallets.
+ * This resolves the friction of keeping track of address derivation indices across CLI or local app sessions.
+ */
+declare class WalletStateStoreJson {
+    private readonly filePath;
+    constructor(options?: WalletStateStoreOptions);
+    /**
+     * Ensures the directory exists before saving.
+     */
+    private ensureDir;
+    /**
+     * Loads the entire state file into memory.
+     */
+    private loadAll;
+    /**
+     * Saves the entire state file to disk.
+     */
+    private saveAll;
+    /**
+     * Retrieves the state for a specific wallet.
+     * If it doesn't exist, returns a default state starting at index 0.
+     */
+    getWallet(walletId: string): WalletState;
+    /**
+     * Saves or overwrites the state for a specific wallet.
+     */
+    saveWallet(wallet: WalletState): void;
+    /**
+     * Atomically gets the next receive index and increments the state.
+     */
+    nextReceiveIndex(walletId: string): number;
+    /**
+     * Atomically gets the next change index and increments the state.
+     */
+    nextChangeIndex(walletId: string): number;
+}
+
+export { AddressManager, type ChainType, type CreateKaspaWalletOptions, DEV_ACCOUNTS_PASSWORD, type DeriveRequest, type DerivedAddress, type EncryptedKeystoreV2, type EvmExportResult, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, HardkasFixtureSigner, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type HelperDeriveRequest, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type NetworkType, type PathRequest, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, type WalletArtifact, type WalletClaims, type WalletCreateRequest, type WalletImportRequest, WalletManager, WalletManagerImpl, type WalletMetadata, type WalletState, WalletStateStoreJson, type WalletStateStoreOptions, appendToKeystoreJson, assertSigningNetworkAllowed, createEmptyRealAccountStore, createLocalKaspaWallet, describeAccount, ensureDevAccounts, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getOrCreateDevAccount, getRealDevAccount, getRequiredEnv, importRealDevAccount, listDevAccountsSync, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, prepareEvmAccountExport, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressNetwork, validateAddressPrefix, withKeystoreLock };

package/dist/index.js

@@ -360,7 +360,6 @@ function listHardkasAccounts(config) {
   }
   const keystoreDir = path2.join(process.cwd(), ".hardkas", "keystore");
   if (fs2.existsSync(keystoreDir)) {
-    const cwd = config?.cwd || process.cwd();
     const files = fs2.readdirSync(keystoreDir);
     for (const file of files) {
       if (file.endsWith(".json")) {
@@ -1558,7 +1557,221 @@ async function appendToKeystoreJson(workspaceRoot, alias, accountData) {
     JSON.parse(written);
   });
 }
+
+// src/address-manager.ts
+import { createHash } from "crypto";
+function resolveChain(chain) {
+  if (chain === "receive" || chain === 0) return 0;
+  if (chain === "change" || chain === 1) return 1;
+  throw new Error(`Invalid chain type: ${chain}`);
+}
+function validateIndex(index, name) {
+  if (!Number.isInteger(index) || index < 0) {
+    throw new Error(`Invalid ${name}: must be a non-negative integer`);
+  }
+}
+var AddressManager = {
+  path(opts) {
+    validateIndex(opts.accountIndex, "accountIndex");
+    validateIndex(opts.addressIndex, "addressIndex");
+    const chainNum = resolveChain(opts.chain);
+    return `m/44'/111111'/${opts.accountIndex}'/${chainNum}/${opts.addressIndex}`;
+  },
+  derive(opts) {
+    const network = opts.network ?? "simnet";
+    if (network === "mainnet") {
+      throw new Error("ADDRESS_MANAGER_MAINNET_BLOCKED: mainnet derivation is blocked by default in simulated v1.");
+    }
+    const derivationPath = this.path({
+      accountIndex: opts.accountIndex,
+      chain: opts.chain,
+      addressIndex: opts.addressIndex
+    });
+    const payload = `${opts.seedRef}:${derivationPath}:${network}`;
+    const hash = createHash("sha256").update(payload).digest("hex").slice(0, 42);
+    const prefix = network.includes("sim") ? "kaspasim" : "kaspatest";
+    const address = `${prefix}:q${hash}`;
+    return {
+      address,
+      path: derivationPath,
+      network,
+      derivationModel: "deterministic-simulated-v1",
+      claims: {
+        realBip39: false,
+        productionCustody: false
+      }
+    };
+  },
+  deriveReceive(opts) {
+    return this.derive({
+      ...opts,
+      chain: 0
+    });
+  },
+  deriveChange(opts) {
+    return this.derive({
+      ...opts,
+      chain: 1
+    });
+  }
+};
+
+// src/wallet-manager.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+var WalletManagerImpl = class {
+  wallets = /* @__PURE__ */ new Map();
+  validateNetwork(network) {
+    const net = network ?? "simnet";
+    if (net === "mainnet") {
+      throw new Error("WALLET_MANAGER_MAINNET_BLOCKED: mainnet custody is blocked by default in simulated v1.");
+    }
+    return net;
+  }
+  generateSeedRef(mnemonic) {
+    return "seedref_" + createHash2("sha256").update(mnemonic).digest("hex").slice(0, 32);
+  }
+  create(opts) {
+    const network = this.validateNetwork(opts.network);
+    const mockMnemonic = `dev-fixture:${opts.walletId}`;
+    const seedRef = this.generateSeedRef(mockMnemonic);
+    const keystoreRef = "keystore_" + randomUUID();
+    const metadata = {
+      walletId: opts.walletId,
+      keystoreRef,
+      network,
+      createdAt: Date.now()
+    };
+    this.wallets.set(opts.walletId, { seedRef, keystoreRef, metadata });
+    return {
+      schema: "hardkas.walletCreated.v1",
+      walletId: opts.walletId,
+      seedRef,
+      keystoreRef,
+      network,
+      claims: {
+        productionCustody: false,
+        plaintextMnemonicStored: false,
+        hardwareWallet: false
+      }
+    };
+  }
+  importMnemonic(opts) {
+    const network = this.validateNetwork(opts.network);
+    const seedRef = this.generateSeedRef(opts.mnemonic);
+    const keystoreRef = "keystore_" + randomUUID();
+    const metadata = {
+      walletId: opts.walletId,
+      keystoreRef,
+      network,
+      createdAt: Date.now()
+    };
+    this.wallets.set(opts.walletId, { seedRef, keystoreRef, metadata });
+    return {
+      schema: "hardkas.walletImported.v1",
+      walletId: opts.walletId,
+      seedRef,
+      keystoreRef,
+      network,
+      claims: {
+        productionCustody: false,
+        plaintextMnemonicStored: false,
+        hardwareWallet: false
+      }
+    };
+  }
+  getSeedRef(walletId) {
+    const state = this.wallets.get(walletId);
+    if (!state) throw new Error("Wallet not found");
+    return state.seedRef;
+  }
+  exportMetadata(walletId) {
+    const state = this.wallets.get(walletId);
+    if (!state) throw new Error("Wallet not found");
+    return state.metadata;
+  }
+};
+var WalletManager = new WalletManagerImpl();
+
+// src/wallet-state-store.ts
+import * as fs6 from "fs";
+import * as path6 from "path";
+var WalletStateStoreJson = class {
+  filePath;
+  constructor(options) {
+    this.filePath = options?.filePath || path6.join(process.cwd(), ".hardkas", "wallet-state.json");
+  }
+  /**
+   * Ensures the directory exists before saving.
+   */
+  ensureDir() {
+    const dir = path6.dirname(this.filePath);
+    if (!fs6.existsSync(dir)) {
+      fs6.mkdirSync(dir, { recursive: true });
+    }
+  }
+  /**
+   * Loads the entire state file into memory.
+   */
+  loadAll() {
+    if (!fs6.existsSync(this.filePath)) {
+      return {};
+    }
+    try {
+      return JSON.parse(fs6.readFileSync(this.filePath, "utf-8"));
+    } catch (e) {
+      process.stderr.write(`[WalletStateStore] corrupt state file at ${this.filePath} \u2014 resetting indices to 0. Cause: ${e}
+`);
+      return {};
+    }
+  }
+  /**
+   * Saves the entire state file to disk.
+   */
+  saveAll(data) {
+    this.ensureDir();
+    const tmp = this.filePath + ".tmp";
+    fs6.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    fs6.renameSync(tmp, this.filePath);
+  }
+  /**
+   * Retrieves the state for a specific wallet.
+   * If it doesn't exist, returns a default state starting at index 0.
+   */
+  getWallet(walletId) {
+    const data = this.loadAll();
+    return data[walletId] || { walletId, receiveIndex: 0, changeIndex: 0 };
+  }
+  /**
+   * Saves or overwrites the state for a specific wallet.
+   */
+  saveWallet(wallet) {
+    const data = this.loadAll();
+    data[wallet.walletId] = wallet;
+    this.saveAll(data);
+  }
+  /**
+   * Atomically gets the next receive index and increments the state.
+   */
+  nextReceiveIndex(walletId) {
+    const wallet = this.getWallet(walletId);
+    const currentIndex = wallet.receiveIndex;
+    wallet.receiveIndex += 1;
+    this.saveWallet(wallet);
+    return currentIndex;
+  }
+  /**
+   * Atomically gets the next change index and increments the state.
+   */
+  nextChangeIndex(walletId) {
+    const wallet = this.getWallet(walletId);
+    const currentIndex = wallet.changeIndex;
+    wallet.changeIndex += 1;
+    this.saveWallet(wallet);
+    return currentIndex;
+  }
+};
 export {
+  AddressManager,
   DEV_ACCOUNTS_PASSWORD,
   HardkasFixtureSigner,
   KaspaSdkKeyGenerator,
@@ -1570,6 +1783,9 @@ export {
   UnsupportedKaspaKeyGenerator,
   UnsupportedRealKaspaSigner,
   UnsupportedRealTxSigner,
+  WalletManager,
+  WalletManagerImpl,
+  WalletStateStoreJson,
   appendToKeystoreJson,
   assertSigningNetworkAllowed,
   createEmptyRealAccountStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/accounts",
-  "version": "0.10.0-alpha",
+  "version": "0.11.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,10 +19,10 @@
   "dependencies": {
     "hash-wasm": "^4.12.0",
     "kaspa-wasm": "0.13.0",
-    "@hardkas/artifacts": "0.10.0-alpha",
-    "@hardkas/config": "0.10.0-alpha",
-    "@hardkas/core": "0.10.0-alpha",
-    "@hardkas/localnet": "0.10.0-alpha"
+    "@hardkas/artifacts": "0.11.0-alpha",
+    "@hardkas/config": "0.11.0-alpha",
+    "@hardkas/core": "0.11.0-alpha",
+    "@hardkas/localnet": "0.11.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",