@cheny56/node-client 1.0.4 → 1.0.6

package/README-COMMONJS.md

@@ -0,0 +1,70 @@
+# CommonJS Usage
+
+This library supports both ES modules (`import`) and CommonJS (`require`). However, due to the ES module nature of the source code, CommonJS usage requires async handling.
+
+## Recommended: Use ES Modules
+
+For the best experience, use ES modules:
+
+```javascript
+// ✅ Recommended
+import { QuorumProvider, ECDSAWallet } from '@cheny56/node-client';
+
+const provider = new QuorumProvider('http://localhost:8545');
+const wallet = new ECDSAWallet('0x...', provider);
+```
+
+## CommonJS Usage (with async/await)
+
+If you must use CommonJS, you need to handle the async loading:
+
+```javascript
+// ⚠️ CommonJS - requires async handling
+const client = await import('@cheny56/node-client');
+const { QuorumProvider, ECDSAWallet } = client;
+
+const provider = new QuorumProvider('http://localhost:8545');
+const wallet = new ECDSAWallet('0x...', provider);
+```
+
+Or wrap in an async function:
+
+```javascript
+async function main() {
+    const { QuorumProvider, ECDSAWallet } = await import('@cheny56/node-client');
+    
+    const provider = new QuorumProvider('http://localhost:8545');
+    const wallet = new ECDSAWallet('0x...', provider);
+    
+    // Use provider and wallet...
+}
+
+main().catch(console.error);
+```
+
+## Why Async is Required
+
+The library source code uses ES modules (`export`/`import`). When using `require()` in CommonJS, Node.js needs to dynamically import the ES module, which is an async operation.
+
+## Migration to ES Modules
+
+To use ES modules in your project:
+
+1. Add `"type": "module"` to your `package.json`, OR
+2. Use `.mjs` extension for your files, OR
+3. Use `import()` syntax in CommonJS files
+
+Example `package.json`:
+```json
+{
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  }
+}
+```
+
+Then you can use:
+```javascript
+import { QuorumProvider } from '@cheny56/node-client';
+```

package/README.md

@@ -10,6 +10,7 @@ A comprehensive JavaScript/TypeScript client library for interacting with Quorum
 - ✅ **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
 
 ## Installation
 
@@ -19,7 +20,7 @@ npm install @cheny56/node-client
 
 ## Quick Start
 
-### Basic Setup
+### JavaScript (ES Modules)
 
 ```javascript
 import { QuorumProvider, ECDSAWallet, PQCWallet, HybridWallet } from '@cheny56/node-client';
@@ -33,6 +34,20 @@ const pqcWallet = new PQCWallet(); // Generates new key pair
 const hybridWallet = new HybridWallet(ecdsaWallet, pqcWallet);
 ```
 
+### TypeScript
+
+```typescript
+import { QuorumProvider, ECDSAWallet, PQCWallet, HybridWallet } from '@cheny56/node-client';
+
+// Connect to Quorum node
+const provider: QuorumProvider = new QuorumProvider('http://localhost:8545');
+
+// 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);
+```
+
 ### Send Native Coin (ETH)
 
 #### ECDSA Transaction
@@ -262,6 +277,16 @@ const token = new ERC20Token(address, provider, wallet);
 - `balanceOf(address)`: Get balance
 - `name()`, `symbol()`, `decimals()`, `totalSupply()`: Token info
 
+## TypeScript Support
+
+This library includes full TypeScript definitions. When using TypeScript, you'll get:
+
+- Full type checking and IntelliSense support
+- Type definitions for all classes, methods, and properties
+- Proper type inference for transaction parameters and return values
+
+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.
+
 ## Examples
 
 See the `examples/` directory for more comprehensive examples:
@@ -278,7 +303,7 @@ See the `examples/` directory for more comprehensive examples:
 ## Dependencies
 
 - `ethers`: ^5.7.2
-- `@noble/post-quantum`: ^1.0.0
+- `@noble/post-quantum`: ^0.5.4
 
 ## License
 

package/index.cjs

@@ -0,0 +1,37 @@
+/**
+ * CommonJS entry point for @cheny56/node-client
+ * 
+ * NOTE: This library is built as ES modules. For CommonJS compatibility,
+ * you need to use dynamic import() instead of require().
+ * 
+ * Example:
+ *   const { QuorumProvider } = await import('@cheny56/node-client');
+ * 
+ * Or use ES modules in your project:
+ *   import { QuorumProvider } from '@cheny56/node-client';
+ */
+
+// Re-export using dynamic import
+// This allows require() to work, but returns a Promise
+const modPromise = import('./src/index.js');
+
+// For synchronous require(), we need to throw a helpful error
+// and suggest using import() or ES modules
+module.exports = new Proxy({}, {
+    get(target, prop) {
+        if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+            // Make it thenable so it works with await import()
+            return modPromise.then(mod => mod[prop]).bind(modPromise);
+        }
+        
+        throw new Error(
+            `Cannot access '${prop}' synchronously. ` +
+            `This package uses ES modules. Please use:\n` +
+            `  const { ${prop} } = await import('@cheny56/node-client');\n` +
+            `Or switch your project to ES modules by adding "type": "module" to package.json`
+        );
+    }
+});
+
+// Also export as a Promise for await import() usage
+module.exports.default = modPromise;

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@cheny56/node-client",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Client library for Quorum blockchain with Post-Quantum Cryptography (PQC) and Zero-Knowledge Proof (ZK) support",
-  "main": "src/index.js",
+  "main": "./index.cjs",
+  "module": "./src/index.js",
+  "types": "src/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "require": "./index.cjs",
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "index.cjs",
+    "package.json",
+    "README.md",
+    "README-COMMONJS.md",
+    "tsconfig.json"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/constants.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Transaction Type Constants
+ */
+export declare const TX_TYPE: {
+    readonly LEGACY: 0;
+    readonly ACCESS_LIST: 1;
+    readonly DYNAMIC_FEE: 2;
+    readonly ZK_PRIVATE: 4;
+};
+
+/**
+ * PQC Signature Type Constants
+ */
+export declare const PQC_TYPE: {
+    readonly NONE: 0;
+    readonly DILITHIUM: 1;
+};
+
+/**
+ * ZK Proof System Constants
+ */
+export declare const ZK_PROOF_SYSTEM: {
+    readonly GROTH16: 1;
+    readonly PLONK: 2;
+    readonly STARK: 3;
+};
+
+/**
+ * Default Chain ID for Quorum
+ */
+export declare const DEFAULT_CHAIN_ID: 1337;

package/src/contract.d.ts

@@ -0,0 +1,63 @@
+import { ethers } from 'ethers';
+import { QuorumProvider } from './provider.js';
+import { ECDSAWallet, PQCWallet, HybridWallet } from './wallet.js';
+
+export declare class Contract {
+    address: string;
+    abi: any[];
+    provider: QuorumProvider;
+    wallet: ECDSAWallet | PQCWallet | HybridWallet | null;
+    contract: ethers.Contract;
+    
+    constructor(
+        address: string,
+        abi: any[],
+        provider: QuorumProvider,
+        wallet?: ECDSAWallet | PQCWallet | HybridWallet | null
+    );
+    
+    connect(wallet: ECDSAWallet | PQCWallet | HybridWallet): Contract;
+    encodeFunctionData(functionName: string, params?: any[]): string;
+    decodeFunctionResult(functionName: string, data: string): any[];
+    call(functionName: string, ...params: any[]): Promise<any>;
+    sendTransaction(
+        functionName: string,
+        params?: any[],
+        txOptions?: any
+    ): Promise<ethers.ContractTransaction>;
+}
+
+export interface TokenTransferOptions {
+    chainId?: number;
+    gasPrice?: bigint;
+    gasLimit?: bigint;
+}
+
+export declare class ERC20Token extends Contract {
+    constructor(
+        address: string,
+        provider: QuorumProvider,
+        wallet?: ECDSAWallet | PQCWallet | HybridWallet | null
+    );
+    
+    name(): Promise<string>;
+    symbol(): Promise<string>;
+    decimals(): Promise<number>;
+    totalSupply(): Promise<ethers.BigNumber>;
+    balanceOf(address: string): Promise<ethers.BigNumber>;
+    transfer(to: string, amount: string | ethers.BigNumber, txOptions?: any): Promise<ethers.ContractTransaction>;
+    transferPQC(
+        wallet: PQCWallet,
+        provider: QuorumProvider,
+        to: string,
+        amount: string | ethers.BigNumber,
+        txOptions?: TokenTransferOptions
+    ): Promise<string>;
+    transferHybrid(
+        wallet: HybridWallet,
+        provider: QuorumProvider,
+        to: string,
+        amount: string | ethers.BigNumber,
+        txOptions?: TokenTransferOptions
+    ): Promise<string>;
+}

package/src/index.d.ts

@@ -0,0 +1,32 @@
+// Providers
+export { QuorumProvider } from './provider.js';
+
+// Wallets
+export { ECDSAWallet, PQCWallet, HybridWallet } from './wallet.js';
+
+// Transactions
+export {
+    LegacyTransaction,
+    PQCLegacyTransaction,
+    HybridLegacyTransaction,
+    AccessListTransaction,
+    PQCAccessListTransaction,
+    DynamicFeeTransaction,
+    PQCDynamicFeeTransaction,
+} from './transaction.js';
+
+// ZK Transactions
+export { ZKTransaction } from './zk-transaction.js';
+
+// Contracts
+export { Contract, ERC20Token } from './contract.js';
+
+// Constants
+export { TX_TYPE, PQC_TYPE, ZK_PROOF_SYSTEM, DEFAULT_CHAIN_ID } from './constants.js';
+
+// Utilities
+export { derivePQCAddress, deriveHybridAddress, isValidAddress } from './utils/address.js';
+export { encodeUint64, encodeBigInt, encodeSignature } from './utils/rlp.js';
+
+// Re-export ethers utilities for convenience
+export { ethers } from 'ethers';

package/src/provider.d.ts

@@ -0,0 +1,52 @@
+import { ethers } from 'ethers';
+
+export declare class QuorumProvider extends ethers.providers.JsonRpcProvider {
+    url: string;
+    
+    constructor(url: string, network?: ethers.providers.Networkish);
+    
+    /**
+     * Send a raw transaction (for PQC/Hybrid transactions)
+     */
+    sendRawTransaction(signedTx: string): Promise<string>;
+    
+    /**
+     * Get transaction receipt
+     */
+    getTransactionReceipt(txHash: string): Promise<ethers.providers.TransactionReceipt>;
+    
+    /**
+     * Wait for transaction to be mined
+     */
+    waitForTransaction(txHash: string, confirmations?: number): Promise<ethers.providers.TransactionReceipt>;
+    
+    /**
+     * Get transaction count (nonce) for an address
+     */
+    getTransactionCount(address: string, blockTag?: ethers.providers.BlockTag): Promise<number>;
+    
+    /**
+     * Get balance for an address
+     */
+    getBalance(address: string, blockTag?: ethers.providers.BlockTag): Promise<ethers.BigNumber>;
+    
+    /**
+     * Estimate gas for a transaction
+     */
+    estimateGas(transaction: ethers.providers.TransactionRequest): Promise<ethers.BigNumber>;
+    
+    /**
+     * Get gas price
+     */
+    getGasPrice(): Promise<ethers.BigNumber>;
+    
+    /**
+     * Get current block number
+     */
+    getBlockNumber(): Promise<number>;
+    
+    /**
+     * Get block by number
+     */
+    getBlock(blockNumber: number | string): Promise<ethers.providers.Block>;
+}

package/src/transaction.d.ts

@@ -0,0 +1,161 @@
+import { ECDSAWallet, PQCWallet } from './wallet.js';
+
+export interface TransactionParams {
+    chainId?: number;
+    nonce?: number;
+    to?: string | null;
+    value?: bigint;
+    data?: string;
+    gasPrice?: bigint;
+    gasLimit?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    maxFeePerGas?: bigint;
+    accessList?: any[];
+}
+
+export declare class LegacyTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    
+    constructor(params: TransactionParams);
+    sign(wallet: ECDSAWallet): Promise<string>;
+    getHex(wallet: ECDSAWallet): Promise<string>;
+}
+
+export declare class PQCLegacyTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    pqcType: number;
+    pqcPubKey: Uint8Array | null;
+    pqcSig: Uint8Array | null;
+    v: number;
+    r: string;
+    s: string;
+    
+    constructor(params: TransactionParams);
+    getSigningHash(): string;
+    sign(wallet: PQCWallet): PQCLegacyTransaction;
+    verify(): boolean;
+    serialize(): Uint8Array;
+    getHex(): string;
+}
+
+export declare class HybridLegacyTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    pqcType: number;
+    pqcPubKey: Uint8Array | null;
+    pqcSig: Uint8Array | null;
+    v: number | null;
+    r: string | null;
+    s: string | null;
+    
+    constructor(params: TransactionParams);
+    getSigningHash(): string;
+    sign(ecdsaWallet: ECDSAWallet, pqcWallet: PQCWallet): HybridLegacyTransaction;
+    verify(): boolean;
+    serialize(): Uint8Array;
+    getHex(): string;
+}
+
+export declare class AccessListTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    accessList: any[];
+    
+    constructor(params: TransactionParams & { accessList?: any[] });
+    sign(wallet: ECDSAWallet): Promise<string>;
+    getHex(wallet: ECDSAWallet): Promise<string>;
+}
+
+export declare class PQCAccessListTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    accessList: any[];
+    pqcType: number;
+    pqcPubKey: Uint8Array | null;
+    pqcSig: Uint8Array | null;
+    v: number;
+    r: string;
+    s: string;
+    
+    constructor(params: TransactionParams & { accessList?: any[] });
+    getSigningHash(): string;
+    sign(wallet: PQCWallet): PQCAccessListTransaction;
+    verify(): boolean;
+    serialize(): Uint8Array;
+    getHex(): string;
+}
+
+export declare class DynamicFeeTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    maxPriorityFeePerGas: bigint;
+    maxFeePerGas: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    accessList: any[];
+    
+    constructor(params: TransactionParams & { accessList?: any[] });
+    sign(wallet: ECDSAWallet): Promise<string>;
+    getHex(wallet: ECDSAWallet): Promise<string>;
+}
+
+export declare class PQCDynamicFeeTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    maxPriorityFeePerGas: bigint;
+    maxFeePerGas: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    accessList: any[];
+    pqcType: number;
+    pqcPubKey: Uint8Array | null;
+    pqcSig: Uint8Array | null;
+    v: number;
+    r: string;
+    s: string;
+    
+    constructor(params: TransactionParams & { accessList?: any[] });
+    getSigningHash(): string;
+    sign(wallet: PQCWallet): PQCDynamicFeeTransaction;
+    verify(): boolean;
+    serialize(): Uint8Array;
+    getHex(): string;
+}

package/src/transaction.js

@@ -4,6 +4,7 @@
  */
 
 import { ethers } from 'ethers';
+// @ts-ignore - @noble/post-quantum may not have TypeScript definitions
 import { ml_dsa65 } from '@noble/post-quantum/ml-dsa';
 import { TX_TYPE, PQC_TYPE, DEFAULT_CHAIN_ID } from './constants.js';
 import { encodeUint64, encodeBigInt, encodeSignature } from './utils/rlp.js';

package/src/utils/address.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Derive PQC address from Dilithium public key
+ */
+export declare function derivePQCAddress(publicKey: Uint8Array): string;
+
+/**
+ * Derive Hybrid address from ECDSA and Dilithium public keys
+ */
+export declare function deriveHybridAddress(ecdsaPublicKey: Uint8Array, dilithiumPublicKey: Uint8Array): string;
+
+/**
+ * Validate Ethereum address format
+ */
+export declare function isValidAddress(address: string): boolean;

package/src/utils/rlp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Encode uint64 value for RLP as hex string
+ */
+export declare function encodeUint64(value: number | bigint | null | undefined): string;
+
+/**
+ * Encode *big.Int value for RLP as hex string
+ */
+export declare function encodeBigInt(value: number | bigint | null | undefined): string;
+
+/**
+ * Encode signature value (R, S) for RLP as hex string
+ */
+export declare function encodeSignature(value: string | null | undefined): string;

package/src/wallet.d.ts

@@ -0,0 +1,45 @@
+import { QuorumProvider } from './provider.js';
+
+export declare class ECDSAWallet {
+    wallet: any;
+    address: string;
+    privateKey: string;
+    provider: QuorumProvider | null;
+    
+    constructor(privateKey: string, provider?: QuorumProvider | null);
+    
+    connect(provider: QuorumProvider): ECDSAWallet;
+    getPublicKey(): string;
+    signMessage(message: string | Uint8Array): Promise<string>;
+}
+
+export declare class PQCWallet {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+    address: string;
+    
+    constructor(secretKey?: Uint8Array | null, publicKey?: Uint8Array | null);
+    
+    static fromSecretKey(secretKey: Uint8Array | string, publicKey: Uint8Array | string): PQCWallet;
+    
+    sign(hash: Uint8Array): Uint8Array;
+    verify(hash: Uint8Array, signature: Uint8Array): boolean;
+    getPublicKeyHex(): string;
+    getSecretKeyHex(): string;
+}
+
+export declare class HybridWallet {
+    ecdsaWallet: ECDSAWallet;
+    pqcWallet: PQCWallet;
+    address: string;
+    
+    constructor(ecdsaWallet: ECDSAWallet | string, pqcWallet: PQCWallet);
+    
+    static fromKeys(
+        ecdsaPrivateKey: string,
+        pqcSecretKey: Uint8Array,
+        pqcPublicKey: Uint8Array
+    ): HybridWallet;
+    
+    connect(provider: QuorumProvider): HybridWallet;
+}

package/src/wallet.js

@@ -4,6 +4,7 @@
  */
 
 import { ethers } from 'ethers';
+// @ts-ignore - @noble/post-quantum may not have TypeScript definitions
 import { ml_dsa65 } from '@noble/post-quantum/ml-dsa';
 import { derivePQCAddress, deriveHybridAddress } from './utils/address.js';
 

package/src/zk-transaction.d.ts

@@ -0,0 +1,45 @@
+import { QuorumProvider } from './provider.js';
+
+export interface ZKTransactionParams {
+    chainId?: number;
+    nonce?: number;
+    to?: string | null;
+    value?: bigint;
+    data?: string;
+    gasPrice?: bigint;
+    gasLimit?: bigint;
+    accessList?: any[];
+    zkProofSystem?: number;
+    zkProof?: Uint8Array | string | null;
+    zkPublicInputs?: (Uint8Array | string)[];
+    zkVerificationKeyHash?: Uint8Array | string | null;
+    encryptedPayload?: Uint8Array | string | null;
+    recipients?: string[];
+    privateFrom?: string | null;
+    privateFor?: string[] | null;
+}
+
+export declare class ZKTransaction {
+    type: number;
+    chainId: number;
+    nonce: number;
+    gasPrice: bigint;
+    gasLimit: bigint;
+    to?: string | null;
+    value: bigint;
+    data: string;
+    accessList: any[];
+    zkProofSystem: number;
+    zkProof: Uint8Array | string | null;
+    zkPublicInputs: (Uint8Array | string)[];
+    zkVerificationKeyHash: Uint8Array | string | null;
+    encryptedPayload: Uint8Array | string | null;
+    recipients: string[];
+    privateFrom: string | null;
+    privateFor: string[] | null;
+    
+    constructor(params: ZKTransactionParams);
+    
+    toZKTxArgs(from: string): any;
+    send(provider: QuorumProvider, from: string): Promise<string>;
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "examples"
+  ]
+}