@cheny56/node-client 1.0.15 → 1.0.16

package/README.md

@@ -1,16 +1,15 @@
-# Quorum Client Library
+# @cheny56/node-client
 
-A comprehensive JavaScript/TypeScript client library for interacting with Quorum blockchain nodes that support Post-Quantum Cryptography (PQC) and Zero-Knowledge Proofs (ZK).
+Client library for Quorum blockchain with Post-Quantum Cryptography (PQC) and Zero-Knowledge Proof (ZK) support.
 
 ## Features
 
-- ✅ **Post-Quantum Cryptography (PQC)**: Full support for Dilithium/ML-DSA-65 signatures
-- ✅ **Zero-Knowledge Proofs (ZK)**: Support for ZK-enhanced transactions
-- ✅ **Hybrid Security**: ECDSA + PQC hybrid transactions for maximum security
-- ✅ **Multiple Transaction Types**: Legacy (Type 0), AccessList (Type 1), DynamicFee (Type 2)
-- ✅ **Token Support**: ERC20 token transfers with PQC and Hybrid signatures
-- ✅ **Ethers.js Compatible**: Built on top of ethers.js for familiar API
-- ✅ **TypeScript Support**: Full TypeScript definitions included
+- **Post-Quantum Cryptography**: Support for Dilithium (ML-DSA-65) signatures
+- **Hybrid Signatures**: Combine ECDSA and PQC for enhanced security
+- **Zero-Knowledge Proofs**: Support for ZK transactions (Groth16, PLONK, STARK)
+- **Transaction Types**: Legacy, AccessList, and DynamicFee transactions
+- **ERC20 Token Support**: Simplified interface for token transfers
+- **CommonJS First**: Uses `require()` syntax by default (JavaScript-friendly)
 
 ## Installation
 
@@ -18,301 +17,475 @@ A comprehensive JavaScript/TypeScript client library for interacting with Quorum
 npm install @cheny56/node-client
 ```
 
+## Dependencies
+
+- `ethers@^5.7.2` - Ethereum library
+- `dilithium-crystals@^1.0.0` - Post-quantum cryptography implementation
+
 ## Quick Start
 
-### JavaScript (ES Modules)
+### Using CommonJS (Default)
 
 ```javascript
-import { QuorumProvider, ECDSAWallet, PQCWallet, HybridWallet } from '@cheny56/node-client';
+const { QuorumProvider, ECDSAWallet, PQCWallet, HybridWallet } = require('@cheny56/node-client');
 
 // Connect to Quorum node
 const provider = new QuorumProvider('http://localhost:8545');
 
-// Create wallets
+// Create ECDSA wallet (synchronous)
 const ecdsaWallet = new ECDSAWallet('0x...', provider);
-const pqcWallet = new PQCWallet(); // Generates new key pair
+
+// Create PQC wallet (async - keys are generated asynchronously)
+const pqcWallet = new PQCWallet();
+await pqcWallet._initPromise; // Wait for keys to be generated
+
+// Or use the static factory method (recommended)
+const pqcWallet2 = await PQCWallet.create();
+
+// Create hybrid wallet
 const hybridWallet = new HybridWallet(ecdsaWallet, pqcWallet);
+const hybridAddress = await hybridWallet.getAddress();
+```
+
+### Using ES Modules (Optional)
+
+```javascript
+import { QuorumProvider, ECDSAWallet, PQCWallet } from '@cheny56/node-client';
+
+// Same usage as CommonJS
+const provider = new QuorumProvider('http://localhost:8545');
+const pqcWallet = await PQCWallet.create();
 ```
 
-### TypeScript
+## Wallets
 
-```typescript
-import { QuorumProvider, ECDSAWallet, PQCWallet, HybridWallet } from '@cheny56/node-client';
+### ECDSA Wallet
 
-// Connect to Quorum node
-const provider: QuorumProvider = new QuorumProvider('http://localhost:8545');
+Standard Ethereum wallet using ECDSA signatures.
+
+```javascript
+const { ECDSAWallet } = require('@cheny56/node-client');
+
+// Create from private key
+const wallet = new ECDSAWallet('0x...', provider);
+
+// Get address
+console.log(wallet.address);
+
+// Sign message
+const signature = await wallet.signMessage('Hello, World!');
+```
+
+### PQC Wallet
+
+Post-quantum wallet using Dilithium signatures. **Note: Key generation is asynchronous.**
+
+```javascript
+const { PQCWallet } = require('@cheny56/node-client');
+
+// Method 1: Create and wait for initialization
+const wallet = new PQCWallet();
+await wallet._initPromise; // Keys are generated in the background
+console.log(wallet.address); // Now available
+
+// Method 2: Use static factory (recommended)
+const wallet2 = await PQCWallet.create();
+console.log(wallet2.address); // Immediately available
+
+// Method 3: Create from existing keys
+const wallet3 = PQCWallet.fromSecretKey(secretKey, publicKey);
+
+// Sign message hash
+const hash = new Uint8Array(32); // Your message hash
+const signature = await wallet.sign(hash);
 
-// Create wallets
-const ecdsaWallet: ECDSAWallet = new ECDSAWallet('0x...', provider);
-const pqcWallet: PQCWallet = new PQCWallet(); // Generates new key pair
-const hybridWallet: HybridWallet = new HybridWallet(ecdsaWallet, pqcWallet);
+// Verify signature
+const isValid = await wallet.verify(hash, signature);
+
+// Get keys (async)
+const publicKeyHex = await wallet.getPublicKeyHex();
+const secretKeyHex = await wallet.getSecretKeyHex();
+```
+
+**Important Notes:**
+- PQC key generation uses `dilithium.keyPair()` which is async
+- Keys are generated in the background when you create a new wallet
+- Always await `_initPromise` or use `PQCWallet.create()` before accessing keys/address
+- The `dilithium-crystals` package returns `{ publicKey, privateKey }` - the library maps `privateKey` to `secretKey` internally
+
+### Hybrid Wallet
+
+Combines ECDSA and PQC signatures for enhanced security.
+
+```javascript
+const { HybridWallet, ECDSAWallet, PQCWallet } = require('@cheny56/node-client');
+
+// Create from ECDSA and PQC wallets
+const ecdsaWallet = new ECDSAWallet('0x...');
+const pqcWallet = await PQCWallet.create();
+const hybridWallet = new HybridWallet(ecdsaWallet, pqcWallet);
+
+// Get hybrid address (async - waits for PQC keys)
+const address = await hybridWallet.getAddress();
+
+// Or use static factory
+const hybridWallet2 = await HybridWallet.create('0x...'); // ECDSA private key
+
+// Create from existing keys
+const hybridWallet3 = HybridWallet.fromKeys(
+    ecdsaPrivateKey,
+    pqcSecretKey,
+    pqcPublicKey
+);
 ```
 
-### Send Native Coin (ETH)
+## Transactions
+
+### Legacy Transactions (Type 0)
 
 #### ECDSA Transaction
 
 ```javascript
-import { LegacyTransaction } from '@cheny56/node-client';
+const { LegacyTransaction } = require('@cheny56/node-client');
 
 const tx = new LegacyTransaction({
-    to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    chainId: 1337,
+    nonce: 0,
+    gasPrice: ethers.utils.parseUnits('20', 'gwei'),
+    gasLimit: 21000,
+    to: '0x...',
     value: ethers.utils.parseEther('1.0'),
-    gasPrice: 0n,
-    gasLimit: 21000n,
 });
 
 const signedTx = await tx.sign(ecdsaWallet);
 const txHash = await provider.sendRawTransaction(signedTx);
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
 #### PQC Transaction
 
 ```javascript
-import { PQCLegacyTransaction } from '@cheny56/node-client';
-
-// Get nonce first
-const nonce = await provider.getTransactionCount(pqcWallet.address, 'pending');
+const { PQCLegacyTransaction } = require('@cheny56/node-client');
 
 const tx = new PQCLegacyTransaction({
     chainId: 1337,
-    nonce: nonce,
-    to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    nonce: 0,
+    gasPrice: 0n, // 0 if node doesn't charge gas
+    gasLimit: 21000,
+    to: '0x...',
     value: ethers.utils.parseEther('1.0'),
-    gasPrice: 0n,
-    gasLimit: 21000n,
 });
 
-tx.sign(pqcWallet);
+// Sign with PQC wallet (async)
+await tx.sign(pqcWallet);
 const serialized = tx.getHex();
 const txHash = await provider.sendRawTransaction(serialized);
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
 #### Hybrid Transaction
 
 ```javascript
-import { HybridLegacyTransaction } from '@cheny56/node-client';
-
-const nonce = await provider.getTransactionCount(hybridWallet.address, 'pending');
+const { HybridLegacyTransaction } = require('@cheny56/node-client');
 
 const tx = new HybridLegacyTransaction({
     chainId: 1337,
-    nonce: nonce,
-    to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    nonce: 0,
+    gasPrice: 0n,
+    gasLimit: 21000,
+    to: '0x...',
     value: ethers.utils.parseEther('1.0'),
+});
+
+// Sign with both wallets (async)
+await tx.sign(ecdsaWallet, pqcWallet);
+const serialized = tx.getHex();
+const txHash = await provider.sendRawTransaction(serialized);
+```
+
+### AccessList Transactions (Type 1)
+
+```javascript
+const { PQCAccessListTransaction } = require('@cheny56/node-client');
+
+const tx = new PQCAccessListTransaction({
+    chainId: 1337,
+    nonce: 0,
     gasPrice: 0n,
-    gasLimit: 21000n,
+    gasLimit: 21000,
+    to: '0x...',
+    value: ethers.utils.parseEther('1.0'),
+    accessList: [],
 });
 
-tx.sign(hybridWallet.ecdsaWallet, hybridWallet.pqcWallet);
+await tx.sign(pqcWallet);
+const serialized = tx.getHex();
+const txHash = await provider.sendRawTransaction(serialized);
+```
+
+### DynamicFee Transactions (Type 2)
+
+```javascript
+const { PQCDynamicFeeTransaction } = require('@cheny56/node-client');
+
+const tx = new PQCDynamicFeeTransaction({
+    chainId: 1337,
+    nonce: 0,
+    maxPriorityFeePerGas: ethers.utils.parseUnits('2', 'gwei'),
+    maxFeePerGas: ethers.utils.parseUnits('20', 'gwei'),
+    gasLimit: 21000,
+    to: '0x...',
+    value: ethers.utils.parseEther('1.0'),
+    accessList: [],
+});
+
+await tx.sign(pqcWallet);
 const serialized = tx.getHex();
 const txHash = await provider.sendRawTransaction(serialized);
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
-### Send ERC20 Tokens
+## ERC20 Tokens
 
-#### Using ECDSA
+### Standard Transfer (ECDSA)
 
 ```javascript
-import { ERC20Token } from '@cheny56/node-client';
+const { ERC20Token } = require('@cheny56/node-client');
 
 const token = new ERC20Token(tokenAddress, provider, ecdsaWallet);
-const tx = await token.transfer(recipientAddress, ethers.utils.parseEther('100'));
-await tx.wait();
+
+// Transfer tokens
+const tx = await token.transfer(recipientAddress, amount, {
+    gasPrice: ethers.utils.parseUnits('20', 'gwei'),
+    gasLimit: 100000,
+});
 ```
 
-#### Using PQC
+### PQC Token Transfer
 
 ```javascript
-import { ERC20Token } from '@cheny56/node-client';
+const { ERC20Token } = require('@cheny56/node-client');
 
 const token = new ERC20Token(tokenAddress, provider);
+
+// Transfer using PQC wallet (async)
 const txHash = await token.transferPQC(
     pqcWallet,
     provider,
     recipientAddress,
-    ethers.utils.parseEther('100'),
-    { chainId: 1337, gasPrice: 0n, gasLimit: 100000n }
+    amount,
+    {
+        chainId: 1337,
+        gasPrice: 0n,
+        gasLimit: 100000,
+    }
 );
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
-#### Using Hybrid
+### Hybrid Token Transfer
 
 ```javascript
-import { ERC20Token } from '@cheny56/node-client';
+const { ERC20Token } = require('@cheny56/node-client');
 
 const token = new ERC20Token(tokenAddress, provider);
+
+// Transfer using hybrid wallet (async)
 const txHash = await token.transferHybrid(
     hybridWallet,
     provider,
     recipientAddress,
-    ethers.utils.parseEther('100'),
-    { chainId: 1337, gasPrice: 0n, gasLimit: 100000n }
+    amount,
+    {
+        chainId: 1337,
+        gasPrice: 0n,
+        gasLimit: 100000,
+    }
 );
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
-### Zero-Knowledge Proof Transactions
+## Zero-Knowledge Proof Transactions
 
 ```javascript
-import { ZKTransaction, ZK_PROOF_SYSTEM } from '@cheny56/node-client';
+const { ZKTransaction, ZK_PROOF_SYSTEM } = require('@cheny56/node-client');
 
 const zkTx = new ZKTransaction({
-    to: contractAddress,
-    value: 0n,
-    data: encodedFunctionData,
+    chainId: 1337,
+    nonce: 0,
     gasPrice: 0n,
-    gasLimit: 100000n,
+    gasLimit: 21000,
+    to: '0x...',
+    value: ethers.utils.parseEther('1.0'),
     zkProofSystem: ZK_PROOF_SYSTEM.GROTH16,
     zkProof: proofBytes,
-    zkPublicInputs: [publicInput1, publicInput2],
+    zkPublicInputs: publicInputs,
     zkVerificationKeyHash: vkHash,
 });
 
 const txHash = await zkTx.send(provider, senderAddress);
-const receipt = await provider.waitForTransaction(txHash);
 ```
 
-## API Reference
-
-### Providers
-
-#### `QuorumProvider`
+## Provider
 
 ```javascript
-const provider = new QuorumProvider(rpcUrl, network);
-```
+const { QuorumProvider } = require('@cheny56/node-client');
 
-**Methods:**
-- `sendRawTransaction(signedTx)`: Send raw transaction
-- `getTransactionReceipt(txHash)`: Get transaction receipt
-- `waitForTransaction(txHash, confirmations)`: Wait for transaction
-- `getTransactionCount(address, blockTag)`: Get nonce
-- `getBalance(address, blockTag)`: Get balance
-- `estimateGas(transaction)`: Estimate gas
-- `getGasPrice()`: Get current gas price
-- `getBlockNumber()`: Get current block number
+const provider = new QuorumProvider('http://localhost:8545');
 
-### Wallets
+// Get block number
+const blockNumber = await provider.getBlockNumber();
 
-#### `ECDSAWallet`
+// Get balance
+const balance = await provider.getBalance(address);
 
-Standard Ethereum wallet using ECDSA signatures.
+// Get transaction count (nonce)
+const nonce = await provider.getTransactionCount(address);
 
-```javascript
-const wallet = new ECDSAWallet(privateKey, provider);
-```
+// Send raw transaction
+const txHash = await provider.sendRawTransaction(signedTxHex);
 
-#### `PQCWallet`
+// Wait for transaction
+const receipt = await provider.waitForTransaction(txHash);
+```
 
-Post-quantum wallet using Dilithium/ML-DSA-65 signatures.
+## Constants
 
 ```javascript
-const wallet = new PQCWallet(); // Generates new key pair
-// or
-const wallet = new PQCWallet(secretKey, publicKey);
+const {
+    TX_TYPE,
+    PQC_TYPE,
+    ZK_PROOF_SYSTEM,
+    DEFAULT_CHAIN_ID,
+} = require('@cheny56/node-client');
+
+// Transaction types
+TX_TYPE.LEGACY        // 0
+TX_TYPE.ACCESS_LIST   // 1
+TX_TYPE.DYNAMIC_FEE   // 2
+TX_TYPE.ZK_PRIVATE   // 4
+
+// PQC types
+PQC_TYPE.NONE        // 0
+PQC_TYPE.DILITHIUM   // 1
+
+// ZK proof systems
+ZK_PROOF_SYSTEM.GROTH16  // 1
+ZK_PROOF_SYSTEM.PLONK    // 2
+ZK_PROOF_SYSTEM.STARK    // 3
+
+// Default chain ID
+DEFAULT_CHAIN_ID  // 1337
 ```
 
-**Methods:**
-- `sign(hash)`: Sign a message hash
-- `verify(hash, signature)`: Verify a signature
-- `getPublicKeyHex()`: Get public key as hex
-- `getSecretKeyHex()`: Get secret key as hex (use with caution!)
-
-#### `HybridWallet`
-
-Hybrid wallet using both ECDSA and PQC signatures.
+## Utilities
 
 ```javascript
-const wallet = new HybridWallet(ecdsaWallet, pqcWallet);
-// or
-const wallet = HybridWallet.fromKeys(ecdsaPrivateKey, pqcSecretKey, pqcPublicKey);
+const {
+    derivePQCAddress,
+    deriveHybridAddress,
+    isValidAddress,
+    encodeUint64,
+    encodeBigInt,
+    encodeSignature,
+} = require('@cheny56/node-client');
+
+// Derive PQC address from public key
+const address = derivePQCAddress(publicKey);
+
+// Derive hybrid address from ECDSA + PQC public keys
+const hybridAddress = deriveHybridAddress(ecdsaPublicKey, pqcPublicKey);
+
+// Validate address
+const isValid = isValidAddress('0x...');
+
+// RLP encoding utilities
+const nonceHex = encodeUint64(5);
+const valueHex = encodeBigInt(ethers.utils.parseEther('1.0'));
+const sigHex = encodeSignature('0x...');
 ```
 
-### Transactions
-
-#### Transaction Types
-
-- `LegacyTransaction`: Type 0, ECDSA only
-- `PQCLegacyTransaction`: Type 0, PQC only
-- `HybridLegacyTransaction`: Type 0, ECDSA + PQC
-- `AccessListTransaction`: Type 1, ECDSA only
-- `PQCAccessListTransaction`: Type 1, PQC only
-- `DynamicFeeTransaction`: Type 2, ECDSA only
-- `PQCDynamicFeeTransaction`: Type 2, PQC only
-
-#### Common Transaction Methods
-
-- `sign(wallet)`: Sign transaction (for ECDSA)
-- `sign(wallet)` or `sign(ecdsaWallet, pqcWallet)`: Sign transaction (for PQC/Hybrid)
-- `getHex()`: Get serialized transaction as hex
-- `verify()`: Verify PQC signature (for PQC transactions)
-
-### Contracts
-
-#### `Contract`
-
-Generic contract interface.
+## Complete Example
 
 ```javascript
-const contract = new Contract(address, abi, provider, wallet);
+const { QuorumProvider, PQCWallet, PQCLegacyTransaction } = require('@cheny56/node-client');
+const { ethers } = require('ethers');
+
+async function main() {
+    // Connect to node
+    const provider = new QuorumProvider('http://localhost:8545');
+    
+    // Create PQC wallet (async)
+    const wallet = await PQCWallet.create();
+    console.log('PQC Address:', wallet.address);
+    
+    // Get nonce
+    const nonce = await provider.getTransactionCount(wallet.address, 'pending');
+    
+    // Create transaction
+    const tx = new PQCLegacyTransaction({
+        chainId: 1337,
+        nonce: nonce,
+        gasPrice: 0n, // 0 if node doesn't charge gas
+        gasLimit: 21000,
+        to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+        value: ethers.utils.parseEther('0.1'),
+    });
+    
+    // Sign transaction (async)
+    await tx.sign(wallet);
+    const serialized = tx.getHex();
+    
+    // Send transaction
+    const txHash = await provider.sendRawTransaction(serialized);
+    console.log('Transaction hash:', txHash);
+    
+    // Wait for confirmation
+    const receipt = await provider.waitForTransaction(txHash);
+    console.log('Transaction confirmed in block:', receipt.blockNumber);
+}
+
+main().catch(console.error);
 ```
 
-#### `ERC20Token`
+## API Reference
 
-ERC20 token interface with PQC and Hybrid support.
+### PQCWallet
+
+#### Constructor
 
 ```javascript
-const token = new ERC20Token(address, provider, wallet);
+new PQCWallet(secretKey?, publicKey?)
 ```
 
-**Methods:**
-- `transfer(to, amount, txOptions)`: Transfer tokens (ECDSA)
-- `transferPQC(wallet, provider, to, amount, txOptions)`: Transfer tokens (PQC)
-- `transferHybrid(wallet, provider, to, amount, txOptions)`: Transfer tokens (Hybrid)
-- `balanceOf(address)`: Get balance
-- `name()`, `symbol()`, `decimals()`, `totalSupply()`: Token info
-
-## TypeScript Support
+- `secretKey` (optional): Existing secret key (Uint8Array or hex string)
+- `publicKey` (optional): Existing public key (Uint8Array or hex string)
+- If both are omitted, keys are generated asynchronously
 
-This library includes full TypeScript definitions. When using TypeScript, you'll get:
+#### Static Methods
 
-- Full type checking and IntelliSense support
-- Type definitions for all classes, methods, and properties
-- Proper type inference for transaction parameters and return values
+- `PQCWallet.create()`: Returns `Promise<PQCWallet>` - Creates wallet with initialized keys
+- `PQCWallet.fromSecretKey(secretKey, publicKey)`: Creates wallet from existing keys
 
-The library is designed to work seamlessly with both JavaScript and TypeScript projects. JavaScript is the primary target, but TypeScript users get full type safety.
+#### Instance Methods
 
-## Examples
+- `async sign(hash: Uint8Array)`: Sign a message hash
+- `async verify(hash: Uint8Array, signature: Uint8Array)`: Verify a signature
+- `async getAddress()`: Get wallet address (waits for initialization if needed)
+- `async getPublicKeyHex()`: Get public key as hex string
+- `async getSecretKeyHex()`: Get secret key as hex string
 
-See the `examples/` directory for more comprehensive examples:
+#### Properties
 
-- `send-coin.js`: Send native coin with different signature types
-- `send-token.js`: Send ERC20 tokens with PQC/Hybrid signatures
-- `zk-transaction.js`: Create and send ZK transactions
+- `secretKey`: Uint8Array (null until initialized)
+- `publicKey`: Uint8Array (null until initialized)
+- `address`: string (null until initialized)
+- `_initialized`: boolean
+- `_initPromise`: Promise - Wait for this to ensure keys are generated
 
-## Requirements
+## Notes
 
-- Node.js 14+
-- Quorum node with PQC and ZK support enabled
-
-## Dependencies
-
-- `ethers`: ^5.7.2
-- `@noble/post-quantum`: ^0.5.4
+- **CommonJS Default**: This library uses CommonJS (`require`) by default for JavaScript compatibility
+- **Async Key Generation**: PQC keys are generated asynchronously - always await initialization before use
+- **Gas Fees**: Set `gasPrice` to `0n` if your Quorum node doesn't charge gas fees
+- **RLP Encoding**: The library uses custom RLP encoding compatible with Go's RLP implementation
+- **Dilithium Package**: Uses `dilithium-crystals` package which returns `{ publicKey, privateKey }` from `keyPair()`
 
 ## License
 
 LGPL-3.0
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## Support
-
-For issues and questions, please open an issue on the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cheny56/node-client",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Client library for Quorum blockchain with Post-Quantum Cryptography (PQC) and Zero-Knowledge Proof (ZK) support",
   "main": "./src/index.js",
   "types": "src/index.d.ts",
@@ -38,11 +38,10 @@
   "author": "",
   "license": "LGPL-3.0",
   "dependencies": {
-    "ethers": "^5.7.2",
-    "dilithium-crystals": "^1.0.0"
+    "@cheny56/node-client": "^1.0.15",
+    "dilithium-crystals": "^1.0.0",
+    "ethers": "^5.7.2"
   },
-  "peerDependencies": {},
-  "devDependencies": {},
   "directories": {
     "example": "examples"
   }