mmn-client-js 1.0.1 → 1.0.3

package/README.md

@@ -1,14 +1,18 @@
 # mmn-client-js
 
-A TypeScript client for interacting with the MMN blockchain via JSON-RPC. It supports creating, signing, and submitting transactions, plus basic account and transaction queries.
+A comprehensive TypeScript client for interacting with the MMN blockchain ecosystem. It provides complete functionality for blockchain transactions, account management, indexer queries, and ZK proof generation.
 
 ## Features
 
-- 🔐 Transaction signing (Ed25519)
-- 📝 Create and sign transactions
-- 🚀 JSON-RPC client for MMN
-- 📦 TypeScript with exported types
-- 🌐 Browser & Node.js compatible
+- 🔐 **Transaction signing** (Ed25519 with NaCl)
+- 📝 **Complete transaction lifecycle** (create, sign, submit)
+- 🚀 **JSON-RPC client** for MMN blockchain
+- 📊 **Indexer client** for transaction history and wallet details
+- � **ZK proof generation** for privacy-preserving authentication
+- 💰 **Wallet management** with BIP39 mnemonic support
+- 🎯 **User ID to address conversion** with SHA256 hashing
+- �📦 **Full TypeScript support** with exported types
+- 🌐 **Cross-platform** (Browser & Node.js compatible)
 
 ## Installation
 
@@ -16,70 +20,199 @@ A TypeScript client for interacting with the MMN blockchain via JSON-RPC. It sup
 npm install mmn-client-js
 ```
 
+Or using yarn:
+
+```bash
+yarn add mmn-client-js
+```
+
 ## Quick Start
 
+### Basic MMN Client Usage
+
 ```typescript
-import { MmnClient } from 'mmn-client-js';
+import { MmnClient, IndexerClient, ZkClient } from 'mmn-client-js';
 
-// Create a client instance
-const client = new MmnClient({
+// Create MMN client for blockchain operations
+const mmnClient = new MmnClient({
   baseUrl: 'http://localhost:8080',
-  timeout: 30000
+  timeout: 30000,
 });
 
+// Generate ephemeral key pair for ZK authentication
+const keyPair = mmnClient.generateEphemeralKeyPair();
+console.log('Public Key:', keyPair.publicKey);
+
+// Convert user ID to blockchain address
+const senderAddress = mmnClient.getAddressFromUserId('user123');
+const recipientAddress = mmnClient.getAddressFromUserId('user456');
+
+// Get current nonce for sender
+const nonceResponse = await mmnClient.getCurrentNonce(senderAddress);
+const currentNonce = nonceResponse.nonce;
+
+// Get account information by user ID
+const account = await mmnClient.getAccountByUserId('user123');
+console.log('Balance:', account.balance);
+
 // Send a transaction
-const response = await client.sendTransaction({
-  sender: 'sender-address',
-  recipient: 'recipient-address',
+const response = await mmnClient.sendTransaction({
+  sender: 'user123',
+  recipient: 'user456',
   amount: '1000000000000000000',
+  nonce: currentNonce + 1,
   textData: 'Hello MMN!',
-  privateKey: 'private-key-hex'
+  publicKey: keyPair.publicKey,
+  privateKey: keyPair.privateKey,
+  zkProof: 'zk-proof-string',
+  zkPub: 'zk-public-string',
 });
 
 if (response.ok) {
   console.log('Transaction Hash:', response.tx_hash);
 } else {
-  console.error('Error:', response.error);
+  console.error('Transaction failed:', response.error);
 }
 ```
 
+### Indexer Client Usage
+
+```typescript
+// Create indexer client for transaction history
+const indexerClient = new IndexerClient({
+  endpoint: 'https://indexer.mmn.network',
+  chainId: 'mmn-mainnet',
+});
+
+// Get transaction history for a wallet
+const transactions = await indexerClient.getTransactionByWallet(
+  'wallet-address',
+  1, // page
+  50, // limit
+  0 // filter: 0=all, 1=received, 2=sent
+);
+
+// Get specific transaction details
+const tx = await indexerClient.getTransactionByHash('tx-hash');
+
+// Get wallet details
+const walletInfo = await indexerClient.getWalletDetail('wallet-address');
+```
+
+### ZK Proof Client Usage
+
+```typescript
+// Create ZK client for proof generation
+const zkClient = new ZkClient({
+  endpoint: 'https://zk.mmn.network',
+  chainId: 'mmn-mainnet',
+});
+
+// Generate ZK proof for authentication
+const zkProof = await zkClient.getZkProofs({
+  userId: 'user123',
+  ephemeralPublicKey: keyPair.publicKey,
+  jwt: 'jwt-token',
+  address: 'wallet-address',
+});
+```
+
 ## API Reference
 
-### Client Configuration
+### MMN Client Configuration
 
 ```typescript
 interface MmnClientConfig {
-  baseUrl: string;                    // MMN JSON-RPC base URL
-  timeout?: number;                   // Request timeout in ms (default: 30000)
-  headers?: Record<string, string>;   // Additional headers
-  axiosConfig?: AxiosRequestConfig;   // Optional axios overrides
+  baseUrl: string; // MMN JSON-RPC base URL
+  timeout?: number; // Request timeout in ms (default: 30000)
+  headers?: Record<string, string>; // Additional headers
+  axiosConfig?: AxiosRequestConfig; // Optional axios overrides
 }
 ```
 
-### Transaction Signing
+### Indexer Client Configuration
 
-The client signs transactions with Ed25519. Provide a 64‑byte secret key or a 32‑byte seed (as `Uint8Array` or string hex/base58).
+```typescript
+interface IndexerClientConfig {
+  endpoint: string; // Indexer API endpoint
+  chainId: string; // Blockchain chain ID
+  timeout?: number; // Request timeout in ms (default: 30000)
+  headers?: Record<string, string>; // Additional headers
+}
+```
+
+### Core Methods
+
+#### MMN Client Methods
+
+**`generateEphemeralKeyPair(): IEphemeralKeyPair`**
+Generate a new Ed25519 key pair using BIP39 mnemonic.
 
-### Transaction Operations
+```typescript
+const keyPair = client.generateEphemeralKeyPair();
+// Returns: { privateKey: string, publicKey: string }
+```
+
+**`getAddressFromUserId(userId: string): string`**
+Convert user ID to blockchain address using SHA256 + Base58.
+
+```typescript
+const address = client.getAddressFromUserId('user123');
+```
 
-#### `sendTransaction(params): Promise<AddTxResponse>`
-Create, sign, and submit a transaction in one call.
+**`sendTransaction(params): Promise<AddTxResponse>`**
+Create, sign, and submit a transaction.
 
 ```typescript
 const response = await client.sendTransaction({
-  sender: 'sender-address',
-  recipient: 'recipient-address',
+  sender: 'user123',
+  recipient: 'user456',
   amount: '1000000000000000000',
-  nonce,
+  nonce: 1,
   textData: 'Optional message',
-  extraInfo: 'Optional extra',
-  privateKey: new Uint8Array(/* 64-byte secretKey */)
+  extraInfo: { type: 'transfer_token', UserSenderId: 'user123', ... },
+  publicKey: 'public-key-base58',
+  privateKey: 'private-key-pkcs8-hex',
+  zkProof: 'zk-proof-string',
+  zkPub: 'zk-public-string'
 });
 ```
 
-## License
+**`getCurrentNonce(address: string, tag?: 'latest' | 'pending'): Promise<GetCurrentNonceResponse>`**
+Get current nonce for an account.
 
-MIT
+**`getAccountByUserId(userId: string): Promise<GetAccountByAddressResponse>`**
+Get account details by user ID.
+
+**`scaleAmountToDecimals(amount: string | number, decimals: number): string`**
+Scale amount to blockchain decimals.
+
+#### Indexer Client Methods
+
+**`getTransactionByHash(hash: string): Promise<Transaction>`**
+Get transaction details by hash.
+
+**`getTransactionByWallet(wallet: string, page: number, limit: number, filter: number): Promise<ListTransactionResponse>`**
+Get transaction history for a wallet.
+
+- `filter`: 0=all, 1=received, 2=sent
+
+**`getWalletDetail(wallet: string): Promise<WalletDetail>`**
+Get wallet balance and account information.
+
+#### ZK Client Methods
+
+**`getZkProofs(params): Promise<IZkProof>`**
+Generate ZK proof for authentication.
+
+```typescript
+const zkProof = await zkClient.getZkProofs({
+  userId: 'user123',
+  ephemeralPublicKey: 'ephemeral-public-key',
+  jwt: 'jwt-token',
+  address: 'wallet-address',
+});
+```
 
 ## Contributing
 

package/dist/index.d.ts

@@ -17,10 +17,13 @@ interface JsonRpcResponse<T = unknown> {
     error?: JsonRpcError;
     id: string | number;
 }
-interface IWallet {
-    address: string;
+interface IEphemeralKeyPair {
     privateKey: string;
-    recoveryPhrase: string;
+    publicKey: string;
+}
+interface IZkProof {
+    proof: string;
+    public_input: string;
 }
 declare enum ETransferType {
     GiveCoffee = "give_coffee",
@@ -47,6 +50,8 @@ interface TxMsg {
     text_data: string;
     nonce: number;
     extra_info: string;
+    zk_proof: string;
+    zk_pub: string;
 }
 interface SignedTx {
     tx_msg: TxMsg;
@@ -110,6 +115,7 @@ interface Transaction {
     status?: number;
     transaction_timestamp: number;
     text_data: string;
+    extra_info: string;
 }
 interface Meta {
     chain_id: number;
@@ -144,6 +150,11 @@ interface IndexerClientConfig {
     timeout?: number;
     headers?: Record<string, string>;
 }
+interface ZkClientConfig {
+    endpoint: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
 
 declare class IndexerClient {
     private axiosInstance;
@@ -162,14 +173,31 @@ declare class MmnClient {
     private requestId;
     constructor(config: MmnClientConfig);
     private makeRequest;
+    /**
+     * Securely convert raw Ed25519 private key to PKCS#8 format
+     * @param raw - Raw 32-byte Ed25519 private key
+     * @returns PKCS#8 formatted private key in hex
+     * @throws Error if input validation fails
+     */
     private rawEd25519ToPkcs8Hex;
-    createWallet(): IWallet;
+    private encodeLength;
+    /**
+     * Securely generate ephemeral key pair with proper entropy
+     * @returns Ephemeral key pair with private and public keys
+     * @throws Error if key generation fails
+     */
+    generateEphemeralKeyPair(): IEphemeralKeyPair;
+    getAddressFromUserId(userId: string): string;
     /**
      * Create and sign a transaction message
      */
     private createAndSignTx;
     /**
-     * Sign a transaction with Ed25519
+     * Securely sign a transaction with Ed25519
+     * @param tx - Transaction message to sign
+     * @param privateKeyHex - Private key in PKCS#8 hex format
+     * @returns Base58 encoded signature
+     * @throws Error if signing fails
      */
     private signTransaction;
     /**
@@ -191,16 +219,32 @@ declare class MmnClient {
         timestamp?: number;
         textData?: string;
         extraInfo?: ExtraInfo;
+        publicKey: string;
         privateKey: string;
+        zkProof: string;
+        zkPub: string;
     }): Promise<AddTxResponse>;
     /**
      * Get current nonce for an account
      */
     getCurrentNonce(address: string, tag?: 'latest' | 'pending'): Promise<GetCurrentNonceResponse>;
-    getAccountByAddress(address: string): Promise<GetAccountByAddressResponse>;
+    getAccountByUserId(userId: string): Promise<GetAccountByAddressResponse>;
     scaleAmountToDecimals(originalAmount: string | number, decimals: number): string;
 }
 declare function createMmnClient(config: MmnClientConfig): MmnClient;
 
-export { ETransferType, IndexerClient, MmnClient, createMmnClient };
-export type { AddTxResponse, ExtraInfo, GetAccountByAddressResponse, GetCurrentNonceResponse, IWallet, IndexerClientConfig, JsonRpcError, JsonRpcRequest, JsonRpcResponse, ListTransactionResponse, Meta, MmnClientConfig, SignedTx, Transaction, TransactionDetailResponse, TxMsg, WalletDetail, WalletDetailResponse };
+declare class ZkClient {
+    private axiosInstance;
+    private endpoint;
+    constructor(config: ZkClientConfig);
+    private makeRequest;
+    getZkProofs({ userId, ephemeralPublicKey, jwt, address, }: {
+        userId: string;
+        ephemeralPublicKey: string;
+        jwt: string;
+        address: string;
+    }): Promise<IZkProof>;
+}
+
+export { ETransferType, IndexerClient, MmnClient, ZkClient, createMmnClient };
+export type { AddTxResponse, ExtraInfo, GetAccountByAddressResponse, GetCurrentNonceResponse, IEphemeralKeyPair, IZkProof, IndexerClientConfig, JsonRpcError, JsonRpcRequest, JsonRpcResponse, ListTransactionResponse, Meta, MmnClientConfig, SignedTx, Transaction, TransactionDetailResponse, TxMsg, WalletDetail, WalletDetailResponse, ZkClientConfig };