@sidhujag/sysweb3-keyring 1.0.544 → 1.0.547

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidhujag/sysweb3-keyring",
-  "version": "1.0.544",
+  "version": "1.0.547",
   "description": "Keyring Manager for UTXO and Web3 Wallets",
   "main": "cjs/index.js",
   "types": "types/index.d.ts",
@@ -11,13 +11,28 @@
   "author": "Pali Wallet",
   "license": "MIT",
   "private": false,
+  "engines": {
+    "yarn": ">= 1.0.0"
+  },
+  "scripts": {
+    "prebuild": "rimraf dist/",
+    "build": "tsc && tsc -p tsconfig.json",
+    "prerelease": "yarn build",
+    "copy": "node ../../scripts/package/copy",
+    "release:npm": "yarn publish ./dist --access=public --no-git-tag-version",
+    "release:preflight": "yarn pack ./dist --dry-run",
+    "publishCode": "yarn prebuild && yarn prerelease && yarn copy && yarn release:npm",
+    "type-check": "tsc --pretty --noEmit",
+    "localTest": "yarn prebuild && yarn build && yarn copy",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
   "dependencies": {
-    "@bitcoinerlab/descriptors": "^2.0.1",
-    "@bitcoinerlab/secp256k1": "^1.0.5",
+    "@bitcoinerlab/secp256k1": "^1.2.0",
     "@ethersproject/abstract-provider": "^5.8.0",
     "@ethersproject/bignumber": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",
-    "@ethersproject/constants": "^5.8.0",
     "@ethersproject/contracts": "^5.8.0",
     "@ethersproject/hdnode": "^5.8.0",
     "@ethersproject/logger": "^5.8.0",
@@ -27,14 +42,13 @@
     "@ethersproject/transactions": "^5.8.0",
     "@ethersproject/units": "^5.8.0",
     "@ethersproject/wallet": "^5.8.0",
-    "@ethersproject/web": "^5.8.0",
     "@ledgerhq/hw-app-eth": "^6.45.12",
     "@ledgerhq/hw-transport-webhid": "^6.30.4",
     "@ledgerhq/logs": "^6.10.1",
     "@metamask/eth-sig-util": "^8.2.0",
     "@sidhujag/sysweb3-core": "^1.0.27",
     "@sidhujag/sysweb3-network": "^1.0.105",
-    "@sidhujag/sysweb3-utils": "^1.0.267",
+    "@sidhujag/sysweb3-utils": "^1.1.270",
     "@trezor/connect-web": "^9.1.5",
     "@trezor/connect-webextension": "^9.6.2",
     "@trezor/utxo-lib": "^1.0.12",
@@ -42,16 +56,20 @@
     "bitcoin-ops": "^1.4.1",
     "bitcoinjs-lib": "^7.0.0-rc.0",
     "crypto-js": "^4.1.1",
-    "dotenv": "^16.4.5",
-    "eth-json-rpc-filters": "^4.2.2",
-    "ethereumjs-util": "^7.1.5",
-    "ledger-bitcoin": "^0.2.3",
-    "satoshi-bitcoin": "^1.0.5"
+    "ethereumjs-util": "^7.1.5"
   },
   "peerDependencies": {
-    "syscoinjs-lib": "^1.0.265"
+    "syscoinjs-lib": "^1.0.267"
   },
   "optionalDependencies": {
     "zksync-ethers": "5"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.1.3",
+    "@types/node": "^20.8.10",
+    "rimraf": "^6.0.1",
+    "syscoinjs-lib": "^1.0.267",
+    "tslib": "^2.8.1",
+    "typescript": "^5.3.3"
   }
-}
+}

package/readme.md

@@ -0,0 +1,201 @@
+# Sysweb3-keyring
+
+A stateless, multi-chain keyring manager for Syscoin and Ethereum-based networks.
+
+## Overview
+
+The sysweb3-keyring provides a unified interface for managing accounts, transactions, and hardware wallets across Syscoin (UTXO) and Ethereum (EVM) networks. The KeyringManager operates statelessly, relying on external state providers (like Redux) for account and network data.
+
+## Key Features
+
+- **Stateless Architecture**: No internal state storage - integrates with external state management
+- **Multi-Chain Support**: Handles both UTXO (Syscoin) and EVM (Ethereum) networks
+- **Hardware Wallet Support**: Trezor and Ledger integration
+- **Secure Session Management**: Encrypted private key handling with session transfer
+- **Transaction Management**: Full transaction lifecycle support for both network types
+
+## Installation
+
+```bash
+npm install @sidhujag/sysweb3-keyring
+# or
+yarn add @sidhujag/sysweb3-keyring
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+import { KeyringManager } from '@sidhujag/sysweb3-keyring';
+
+// Create a vault state getter function (e.g., from Redux store)
+const vaultStateGetter = () => store.getState().vault;
+
+// Initialize the keyring manager
+const keyringManager = await KeyringManager.createInitialized(
+  seedPhrase,
+  password,
+  vaultStateGetter
+);
+```
+
+### Account Management
+
+```javascript
+// Get active account
+const activeAccount = keyringManager.getActiveAccount();
+
+// Create new account
+const newAccount = await keyringManager.addNewAccount('My Account');
+
+// Switch active account
+await keyringManager.setActiveAccount(accountId, KeyringAccountType.HDAccount);
+
+// Import account from private key
+const importedAccount = await keyringManager.importAccount(
+  privateKey,
+  'Imported Account'
+);
+```
+
+### Network Management
+
+```javascript
+// Set network (automatically switches between UTXO/EVM signers)
+await keyringManager.setSignerNetwork(networkConfig);
+
+// Get current network
+const network = keyringManager.getNetwork();
+```
+
+### Transaction Operations
+
+#### Syscoin (UTXO) Transactions
+
+```javascript
+// Estimate transaction fee
+const feeEstimate =
+  await keyringManager.syscoinTransaction.getEstimateSysTransactionFee({
+    txOptions: {},
+    amount: 1.0,
+    receivingAddress: 'sys1q...',
+    feeRate: 0.00001,
+    token: null,
+  });
+
+// Sign PSBT
+const signedPsbt = await keyringManager.syscoinTransaction.signPSBT({
+  psbt: psbtData,
+  isTrezor: false,
+  isLedger: false,
+});
+
+// Get addresses
+const receivingAddress = await keyringManager.updateReceivingAddress();
+const changeAddress = await keyringManager.getNewChangeAddress();
+```
+
+#### Ethereum (EVM) Transactions
+
+```javascript
+// Send transaction
+const txHash = await keyringManager.ethereumTransaction.sendTransaction({
+  to: '0x...',
+  value: '1000000000000000000', // 1 ETH in wei
+  gasLimit: '21000',
+  gasPrice: '20000000000', // 20 gwei
+});
+
+// Sign message
+const signature = await keyringManager.ethereumTransaction.signPersonalMessage([
+  '0x48656c6c6f', // "Hello" in hex
+  accountAddress,
+]);
+```
+
+### Hardware Wallet Support
+
+```javascript
+// Import Trezor account
+const trezorAccount = await keyringManager.importTrezorAccount(
+  'Trezor Account'
+);
+
+// Import Ledger account
+const ledgerAccount = await keyringManager.importLedgerAccount(
+  false,
+  'Ledger Account'
+);
+```
+
+### State Management Integration
+
+The KeyringManager requires a `vaultStateGetter` function that returns the current vault state:
+
+```javascript
+// Example with Redux
+const vaultStateGetter = () => ({
+  accounts: {
+    [KeyringAccountType.HDAccount]: {
+      /* account data */
+    },
+    [KeyringAccountType.Imported]: {
+      /* imported accounts */
+    },
+  },
+  activeAccount: { id: 0, type: KeyringAccountType.HDAccount },
+  activeNetwork: {
+    /* network config */
+  },
+  // ... other vault state
+});
+
+// The keyring manager will call this function to get current state
+const keyringManager = new KeyringManager();
+keyringManager.setVaultStateGetter(vaultStateGetter);
+```
+
+## Architecture
+
+The stateless design means:
+
+- **No Internal State**: The KeyringManager doesn't store account or network data
+- **External State Provider**: Relies on your application's state management (Redux, Context, etc.)
+- **Session Management**: Private keys are encrypted and managed securely in memory
+- **Multi-Instance Support**: Multiple KeyringManager instances can operate independently
+
+## API Reference
+
+### KeyringManager
+
+Main class for keyring operations:
+
+- `createInitialized(seedPhrase, password, vaultStateGetter)` - Create and initialize keyring
+- `addNewAccount(label?)` - Create new HD account
+- `setActiveAccount(id, type)` - Switch active account
+- `importAccount(privateKey, label?)` - Import account from private key
+- `setSignerNetwork(network)` - Set active network
+- `unlock(password)` - Unlock keyring
+- `lockWallet()` - Lock keyring
+
+### Transaction Managers
+
+- `syscoinTransaction` - UTXO transaction operations
+- `ethereumTransaction` - EVM transaction operations
+
+### Hardware Wallet Support
+
+- `importTrezorAccount(label?)` - Import Trezor account
+- `importLedgerAccount(isConnected, label?)` - Import Ledger account
+
+## Security
+
+- Private keys are encrypted and stored in memory only
+- Session data is cleared when the keyring is locked
+- Hardware wallet integration follows device security models
+- Secure memory management with explicit cleanup
+
+## License
+
+MIT License

package/src/declare.d.ts

@@ -0,0 +1,7 @@
+declare module 'syscoinjs-lib';
+declare module '@sidhujag/sysweb3-core';
+declare module 'bip32-path';
+interface Window {
+  pali: Readonly<any>;
+}
+//TODO: remove window dependence

package/src/errorUtils.ts

@@ -0,0 +1,83 @@
+export function handleStatusCodeError(
+  statusCode: number,
+  errorMessage: string
+) {
+  switch (statusCode) {
+    case 400:
+      console.error({
+        errorMessage,
+        message:
+          'Bad Request: The current provider(RPC) could not understand the request due to invalid syntax.',
+      });
+      break;
+    case 401:
+      console.error({
+        errorMessage,
+        message: 'Unauthorized: The request requires user authentication.',
+      });
+      break;
+    case 403:
+      console.error({
+        errorMessage,
+        message:
+          'Forbidden: You do not have the necessary permissions for the resource.',
+      });
+      break;
+    case 404:
+      console.error({
+        errorMessage,
+        message: 'Not Found: The requested RPC method could not be found.',
+      });
+      break;
+    case 405:
+      console.error({
+        errorMessage,
+        message:
+          'Method Not Allowed: The request method is known by the current provider but is not supported by the target resource.',
+      });
+      break;
+    case 408:
+      console.error({
+        errorMessage,
+        message:
+          'Request Timeout: The current provider(RPC) would like to shut down the unused connection.',
+      });
+      break;
+    case 413:
+      console.error({
+        errorMessage,
+        message:
+          'Payload Too Large: The request entity is larger than limits defined by the server.',
+      });
+      break;
+    case 429:
+      console.error({
+        errorMessage,
+        message:
+          'The current RPC provider has a low rate-limit. We are applying a cooldown that will affect Pali performance. Modify the RPC URL in the network settings to resolve this issue.',
+      });
+      throw {
+        errorMessage,
+        message:
+          'The current RPC provider has a low rate-limit. We are applying a cooldown that will affect Pali performance. Modify the RPC URL in the network settings to resolve this issue.',
+      };
+    case 500:
+      console.error({
+        errorMessage,
+        message:
+          'Internal Server Error: The current provider(RPC) encountered an unexpected condition that prevented it from fulfilling the request.',
+      });
+      break;
+    case 503:
+      console.error({
+        errorMessage,
+        message:
+          'Service Unavailable: The current provider(RPC) is not ready to handle the request, possibly due to being down for maintenance or overloaded.',
+      });
+      break;
+    default:
+      throw {
+        message: `Unexpected HTTP status code: ${statusCode}`,
+      };
+  }
+}