@noosphere/crypto 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,231 @@
+import { ethers } from 'ethers';
+
+/**
+ * Types for Noosphere crypto package
+ */
+/**
+ * Keystore format for storing EOA and payment wallets
+ */
+interface NoosphereKeystore {
+    version: string;
+    eoa: {
+        address: string;
+        keystore: string;
+    };
+    paymentWallets: {
+        [walletAddress: string]: {
+            address: string;
+            privateKey: string;
+            subscriptionId?: string;
+            createdAt: string;
+            metadata?: Record<string, any>;
+        };
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Payment wallet information
+ */
+interface PaymentWalletInfo {
+    address: string;
+    subscriptionId?: string;
+    createdAt: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Keystore information (without decrypting)
+ */
+interface KeystoreInfo {
+    version: string;
+    eoaAddress: string;
+    paymentWalletCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * KeystoreManager manages EOA and payment wallets in a single encrypted keystore file
+ * This follows the Hub's keystore structure
+ */
+declare class KeystoreManager {
+    private keystorePath;
+    private password;
+    private keystore;
+    constructor(keystorePath: string, password: string);
+    /**
+     * Initialize a new keystore with an EOA
+     * @param privateKey - Private key of the EOA (agent's main wallet)
+     * @param provider - Ethereum provider
+     */
+    static initialize(keystorePath: string, password: string, privateKey: string, provider: ethers.Provider): Promise<KeystoreManager>;
+    /**
+     * Load existing keystore
+     */
+    load(): Promise<void>;
+    /**
+     * Get the EOA wallet
+     */
+    getEOA(provider: ethers.Provider): Promise<ethers.Wallet>;
+    /**
+     * Get EOA address without decrypting
+     */
+    getEOAAddress(): string;
+    /**
+     * Add a payment wallet to the keystore
+     * @param walletAddress - Address of the payment wallet
+     * @param privateKey - Private key of the payment wallet
+     * @param subscriptionId - Optional subscription ID this wallet is for
+     */
+    addPaymentWallet(walletAddress: string, privateKey: string, subscriptionId?: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Get a payment wallet
+     */
+    getPaymentWallet(walletAddress: string, provider: ethers.Provider): Promise<ethers.Wallet>;
+    /**
+     * List all payment wallet addresses
+     */
+    listPaymentWallets(): PaymentWalletInfo[];
+    /**
+     * Remove a payment wallet
+     */
+    removePaymentWallet(walletAddress: string): Promise<void>;
+    /**
+     * Get keystore info without decrypting
+     */
+    getInfo(): KeystoreInfo;
+    /**
+     * Check if a payment wallet exists
+     */
+    hasPaymentWallet(walletAddress: string): boolean;
+    /**
+     * Update EOA (re-encrypt with new password or new private key)
+     */
+    updateEOA(newPrivateKey: string, provider: ethers.Provider): Promise<void>;
+    /**
+     * Save keystore to disk
+     */
+    private save;
+    /**
+     * Encrypt data using password
+     * Uses a simple base64 encoding for now - in production, use proper encryption
+     */
+    private encryptData;
+    /**
+     * Decrypt data using password
+     */
+    private decryptData;
+    /**
+     * Export keystore for backup
+     */
+    exportKeystore(): Promise<string>;
+    /**
+     * Import keystore from backup
+     */
+    static importKeystore(keystorePath: string, password: string, keystoreJson: string): Promise<KeystoreManager>;
+    /**
+     * Change password (re-encrypt all wallets)
+     */
+    changePassword(oldPassword: string, newPassword: string, provider: ethers.Provider): Promise<void>;
+}
+
+declare class WalletManager {
+    private wallet;
+    private provider;
+    private keystoreManager?;
+    constructor(privateKey: string, provider: ethers.Provider, keystoreManager?: KeystoreManager);
+    /**
+     * Initialize WalletManager from KeystoreManager
+     * This is the recommended way to create a WalletManager for production use
+     */
+    static fromKeystoreManager(keystoreManager: KeystoreManager, provider: ethers.Provider): Promise<WalletManager>;
+    /**
+     * Get the agent's wallet address
+     */
+    getAddress(): string;
+    /**
+     * Get the wallet instance
+     */
+    getWallet(): ethers.Wallet;
+    /**
+     * Generate deterministic payment wallet using HDNode derivation
+     * @param subscriptionId - Subscription ID to derive wallet for
+     */
+    getDeterministicPaymentWallet(subscriptionId: bigint): Promise<string>;
+    /**
+     * Get or generate mnemonic for HD wallet derivation
+     */
+    private getMnemonic;
+    /**
+     * Sign EIP-712 typed data for delegated subscription creation
+     */
+    signTypedData(domain: ethers.TypedDataDomain, types: Record<string, ethers.TypedDataField[]>, value: Record<string, any>): Promise<string>;
+    /**
+     * Get current ETH balance
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Get ERC20 token balance
+     */
+    getTokenBalance(tokenAddress: string): Promise<bigint>;
+    /**
+     * Load wallet from keystore file
+     */
+    static fromKeystore(keystorePath: string, password: string, provider: ethers.Provider): Promise<WalletManager>;
+    /**
+     * Save wallet to encrypted keystore file
+     */
+    toKeystore(password: string, outputPath: string): Promise<void>;
+    /**
+     * Create a new payment wallet using WalletFactory contract
+     * @param walletFactoryAddress - Address of the WalletFactory contract
+     * @param initialOwner - Address that will own the new wallet (typically subscription owner)
+     * @param subscriptionId - Optional subscription ID to associate with this wallet
+     * @returns Transaction receipt and new wallet address
+     */
+    createPaymentWallet(walletFactoryAddress: string, initialOwner: string, subscriptionId?: string): Promise<{
+        walletAddress: string;
+        txHash: string;
+    }>;
+    /**
+     * Create a new EOA payment wallet and save to keystore
+     * This creates a regular externally-owned account (EOA) wallet
+     * @param subscriptionId - Optional subscription ID to associate with this wallet
+     * @returns Wallet address and private key (for immediate use, then should be discarded)
+     */
+    createEOAPaymentWallet(subscriptionId?: string): Promise<{
+        walletAddress: string;
+        privateKey: string;
+    }>;
+    /**
+     * Get a payment wallet from keystore
+     */
+    getPaymentWallet(walletAddress: string): Promise<ethers.Wallet>;
+    /**
+     * List all payment wallets in keystore
+     */
+    listPaymentWallets(): Array<{
+        address: string;
+        subscriptionId?: string;
+    }>;
+    /**
+     * Check if a wallet address was created by WalletFactory
+     * @param walletFactoryAddress - Address of the WalletFactory contract
+     * @param walletAddress - Wallet address to validate
+     * @returns True if wallet was created by this factory
+     */
+    isValidWallet(walletFactoryAddress: string, walletAddress: string): Promise<boolean>;
+    /**
+     * Fund a payment wallet with ETH
+     * @param walletAddress - Address of the wallet to fund
+     * @param amount - Amount in ETH as string (e.g., "0.1")
+     */
+    fundWallet(walletAddress: string, amount: string): Promise<string>;
+    /**
+     * Get balance of a payment wallet
+     * @param walletAddress - Address of the wallet to check
+     */
+    getWalletBalance(walletAddress: string): Promise<bigint>;
+}
+
+export { type KeystoreInfo, KeystoreManager, type NoosphereKeystore, type PaymentWalletInfo, WalletManager };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { ethers } from 'ethers';
+
+/**
+ * Types for Noosphere crypto package
+ */
+/**
+ * Keystore format for storing EOA and payment wallets
+ */
+interface NoosphereKeystore {
+    version: string;
+    eoa: {
+        address: string;
+        keystore: string;
+    };
+    paymentWallets: {
+        [walletAddress: string]: {
+            address: string;
+            privateKey: string;
+            subscriptionId?: string;
+            createdAt: string;
+            metadata?: Record<string, any>;
+        };
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Payment wallet information
+ */
+interface PaymentWalletInfo {
+    address: string;
+    subscriptionId?: string;
+    createdAt: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Keystore information (without decrypting)
+ */
+interface KeystoreInfo {
+    version: string;
+    eoaAddress: string;
+    paymentWalletCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * KeystoreManager manages EOA and payment wallets in a single encrypted keystore file
+ * This follows the Hub's keystore structure
+ */
+declare class KeystoreManager {
+    private keystorePath;
+    private password;
+    private keystore;
+    constructor(keystorePath: string, password: string);
+    /**
+     * Initialize a new keystore with an EOA
+     * @param privateKey - Private key of the EOA (agent's main wallet)
+     * @param provider - Ethereum provider
+     */
+    static initialize(keystorePath: string, password: string, privateKey: string, provider: ethers.Provider): Promise<KeystoreManager>;
+    /**
+     * Load existing keystore
+     */
+    load(): Promise<void>;
+    /**
+     * Get the EOA wallet
+     */
+    getEOA(provider: ethers.Provider): Promise<ethers.Wallet>;
+    /**
+     * Get EOA address without decrypting
+     */
+    getEOAAddress(): string;
+    /**
+     * Add a payment wallet to the keystore
+     * @param walletAddress - Address of the payment wallet
+     * @param privateKey - Private key of the payment wallet
+     * @param subscriptionId - Optional subscription ID this wallet is for
+     */
+    addPaymentWallet(walletAddress: string, privateKey: string, subscriptionId?: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Get a payment wallet
+     */
+    getPaymentWallet(walletAddress: string, provider: ethers.Provider): Promise<ethers.Wallet>;
+    /**
+     * List all payment wallet addresses
+     */
+    listPaymentWallets(): PaymentWalletInfo[];
+    /**
+     * Remove a payment wallet
+     */
+    removePaymentWallet(walletAddress: string): Promise<void>;
+    /**
+     * Get keystore info without decrypting
+     */
+    getInfo(): KeystoreInfo;
+    /**
+     * Check if a payment wallet exists
+     */
+    hasPaymentWallet(walletAddress: string): boolean;
+    /**
+     * Update EOA (re-encrypt with new password or new private key)
+     */
+    updateEOA(newPrivateKey: string, provider: ethers.Provider): Promise<void>;
+    /**
+     * Save keystore to disk
+     */
+    private save;
+    /**
+     * Encrypt data using password
+     * Uses a simple base64 encoding for now - in production, use proper encryption
+     */
+    private encryptData;
+    /**
+     * Decrypt data using password
+     */
+    private decryptData;
+    /**
+     * Export keystore for backup
+     */
+    exportKeystore(): Promise<string>;
+    /**
+     * Import keystore from backup
+     */
+    static importKeystore(keystorePath: string, password: string, keystoreJson: string): Promise<KeystoreManager>;
+    /**
+     * Change password (re-encrypt all wallets)
+     */
+    changePassword(oldPassword: string, newPassword: string, provider: ethers.Provider): Promise<void>;
+}
+
+declare class WalletManager {
+    private wallet;
+    private provider;
+    private keystoreManager?;
+    constructor(privateKey: string, provider: ethers.Provider, keystoreManager?: KeystoreManager);
+    /**
+     * Initialize WalletManager from KeystoreManager
+     * This is the recommended way to create a WalletManager for production use
+     */
+    static fromKeystoreManager(keystoreManager: KeystoreManager, provider: ethers.Provider): Promise<WalletManager>;
+    /**
+     * Get the agent's wallet address
+     */
+    getAddress(): string;
+    /**
+     * Get the wallet instance
+     */
+    getWallet(): ethers.Wallet;
+    /**
+     * Generate deterministic payment wallet using HDNode derivation
+     * @param subscriptionId - Subscription ID to derive wallet for
+     */
+    getDeterministicPaymentWallet(subscriptionId: bigint): Promise<string>;
+    /**
+     * Get or generate mnemonic for HD wallet derivation
+     */
+    private getMnemonic;
+    /**
+     * Sign EIP-712 typed data for delegated subscription creation
+     */
+    signTypedData(domain: ethers.TypedDataDomain, types: Record<string, ethers.TypedDataField[]>, value: Record<string, any>): Promise<string>;
+    /**
+     * Get current ETH balance
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Get ERC20 token balance
+     */
+    getTokenBalance(tokenAddress: string): Promise<bigint>;
+    /**
+     * Load wallet from keystore file
+     */
+    static fromKeystore(keystorePath: string, password: string, provider: ethers.Provider): Promise<WalletManager>;
+    /**
+     * Save wallet to encrypted keystore file
+     */
+    toKeystore(password: string, outputPath: string): Promise<void>;
+    /**
+     * Create a new payment wallet using WalletFactory contract
+     * @param walletFactoryAddress - Address of the WalletFactory contract
+     * @param initialOwner - Address that will own the new wallet (typically subscription owner)
+     * @param subscriptionId - Optional subscription ID to associate with this wallet
+     * @returns Transaction receipt and new wallet address
+     */
+    createPaymentWallet(walletFactoryAddress: string, initialOwner: string, subscriptionId?: string): Promise<{
+        walletAddress: string;
+        txHash: string;
+    }>;
+    /**
+     * Create a new EOA payment wallet and save to keystore
+     * This creates a regular externally-owned account (EOA) wallet
+     * @param subscriptionId - Optional subscription ID to associate with this wallet
+     * @returns Wallet address and private key (for immediate use, then should be discarded)
+     */
+    createEOAPaymentWallet(subscriptionId?: string): Promise<{
+        walletAddress: string;
+        privateKey: string;
+    }>;
+    /**
+     * Get a payment wallet from keystore
+     */
+    getPaymentWallet(walletAddress: string): Promise<ethers.Wallet>;
+    /**
+     * List all payment wallets in keystore
+     */
+    listPaymentWallets(): Array<{
+        address: string;
+        subscriptionId?: string;
+    }>;
+    /**
+     * Check if a wallet address was created by WalletFactory
+     * @param walletFactoryAddress - Address of the WalletFactory contract
+     * @param walletAddress - Wallet address to validate
+     * @returns True if wallet was created by this factory
+     */
+    isValidWallet(walletFactoryAddress: string, walletAddress: string): Promise<boolean>;
+    /**
+     * Fund a payment wallet with ETH
+     * @param walletAddress - Address of the wallet to fund
+     * @param amount - Amount in ETH as string (e.g., "0.1")
+     */
+    fundWallet(walletAddress: string, amount: string): Promise<string>;
+    /**
+     * Get balance of a payment wallet
+     * @param walletAddress - Address of the wallet to check
+     */
+    getWalletBalance(walletAddress: string): Promise<bigint>;
+}
+
+export { type KeystoreInfo, KeystoreManager, type NoosphereKeystore, type PaymentWalletInfo, WalletManager };