@sidhujag/sysweb3-keyring 2.1.3 → 2.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.1.4
+
+- Require a fixed keyring host with explicit storage and session authority. Device unlock remains an optional capability.
+- Require transaction approval, exact signed-envelope validation and durable submission boundaries for EVM and UTXO sends. Ledger and Trezor signing use the same approval boundary as software signing.
+- Use canonical base units for ERC-20 amounts and explicit owned endpoint verification for UTXO reads. Preserve existing vault readers and platform transports.
+
 ## 2.1.2
 
 - Preserve explicit hardware transaction nonces, including zero, instead of replacing them with the pending RPC nonce.

package/README.md

@@ -40,20 +40,12 @@ values; the built-in memory client provides this operation synchronously.
 There is no sequential or unlocked fallback. A backend shared across storage
 partitions needs its own atomic implementation or a single owner.
 
-### Release order for 1.0.613
-
-Publish `@sidhujag/sysweb3-core@1.0.29` before `@sidhujag/sysweb3-keyring@1.0.613`.
-The updated lock entry describes that intended dependency; its integrity is
-intentionally absent until publication. Regenerate and verify the lockfile from
-the published registry artifacts before a clean registry installation. Local
-validation uses the built package tarballs and does not establish publication.
-
 ## Installation
 
 ```bash
-npm install @sidhujag/sysweb3-keyring
+npm install @sidhujag/sysweb3-keyring syscoinjs-lib@1.0.279
 # or
-yarn add @sidhujag/sysweb3-keyring
+yarn add @sidhujag/sysweb3-keyring syscoinjs-lib@1.0.279
 ```
 
 ## Usage
@@ -61,19 +53,29 @@ yarn add @sidhujag/sysweb3-keyring
 ### Basic Setup
 
 ```javascript
-import { KeyringManager } from '@sidhujag/sysweb3-keyring';
+import { createKeyringHost, 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 walletHost = createKeyringHost(walletStorage);
+const walletOptions = {
+  ledgerHost: authorizedLedgerHostPort,
+  captureEvmSubmission: captureReviewedSubmission,
+};
 const keyringManager = await KeyringManager.createInitialized(
+  walletHost,
   seedPhrase,
   password,
-  vaultStateGetter
+  vaultStateGetter,
+  walletOptions
 );
 ```
 
+The application supplies fixed wallet storage and a durable submission
+capability. The capability checks the active approval and persists exact
+signed bytes before the SDK can broadcast them.
+
 ### Account Management
 
 ```javascript
@@ -108,38 +110,34 @@ const network = keyringManager.getNetwork();
 #### 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,
-});
+const quote = await keyringManager.syscoinTransaction.getEstimateSysTransactionFee(
+  { amount: reviewedAmount, receivingAddress: reviewedRecipient },
+  draftUtxoRead
+);
 
-// Get addresses
-const receivingAddress = await keyringManager.updateReceivingAddress();
-const changeAddress = await keyringManager.getNewChangeAddress();
+// Review the exact PSBT and capture its approval before signing.
+const signedPsbt = await keyringManager.syscoinTransaction.signPSBT(
+  { psbt: reviewedPsbt },
+  approvedUtxoRead
+);
+
+const receivingAddress = await keyringManager.updateReceivingAddress(accountUtxoRead);
+const changeAddress = await keyringManager.getNewChangeAddress(accountUtxoRead);
 ```
 
+Each UTXO read owner supplies a bounded endpoint-specific `fetch`, an abort
+signal and a synchronous account, network and session guard. A signing owner
+also binds the approved PSBT to that context.
+
 #### 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
-});
+// Submit a fully specified transaction after approval.
+const submitted = await keyringManager.ethereumTransaction.sendFormattedTransaction(
+  reviewedTransaction,
+  undefined,
+  { mode: 'reviewed-native', assertCurrent: assertReviewCurrent }
+);
 
 // Sign message
 const signature = await keyringManager.ethereumTransaction.signPersonalMessage([
@@ -212,7 +210,7 @@ const vaultStateGetter = () => ({
 });
 
 // The keyring manager will call this function to get current state
-const keyringManager = new KeyringManager();
+const keyringManager = new KeyringManager(walletHost, walletOptions);
 keyringManager.setVaultStateGetter(vaultStateGetter);
 ```
 
@@ -231,7 +229,7 @@ The stateless design means:
 
 Main class for keyring operations:
 
-- `createInitialized(seedPhrase, password, vaultStateGetter)` - Create and initialize keyring
+- `createInitialized(host, seedPhrase, password, vaultStateGetter, options)` - Create and initialize keyring
 - `addNewAccount(label?)` - Create new HD account
 - `setActiveAccount(id, type)` - Switch active account
 - `importAccount(privateKey, label?)` - Import account from private key
@@ -244,12 +242,11 @@ Main class for keyring operations:
 - `syscoinTransaction` - UTXO transaction operations
 - `ethereumTransaction` - EVM transaction operations
 
-For application-specific approval rules, pass an optional third argument to
-`ethereumTransaction.sendFormattedTransaction(params, isLegacy, { assertCurrent })`.
+The formatted-send options require an explicit mode and an approval guard.
 The guard must return `undefined` synchronously or throw to deny the operation.
-It supplements the SDK's account, network and session checks and is rechecked
-after asynchronous preparation, immediately before signing, and before broadcast.
-It is not called after a broadcast acknowledgement to reclassify a sent transaction.
+The SDK combines it with account, network and session checks at signing and
+broadcast. Once broadcast is acknowledged, the transaction remains recorded
+even if the approval has since expired.
 
 ### Hardware Wallet Support
 
@@ -339,7 +336,10 @@ const host = createLedgerDmkHost({
 });
 
 // Wallet authority: use a secured semantic port to that page, not a raw APDU port.
-const wallet = new KeyringManager(undefined, authorizedLedgerHostPort);
+const wallet = new KeyringManager(walletHost, {
+  ledgerHost: authorizedLedgerHostPort,
+  captureEvmSubmission: captureReviewedSubmission,
+});
 ```
 
 Use only the ESM host entry with a browser bundler and its required platform

package/cjs/hardware-transaction-authority.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureHardwareTransactionAuthority = captureHardwareTransactionAuthority;
+const retiredApproval = () => Object.assign(new Error('Hardware signing approval is no longer current'), {
+    name: 'AbortError',
+    code: 'HARDWARE_REQUEST_CANCELLED',
+    transactionNotBroadcast: true,
+});
+function captureHardwareTransactionAuthority(authority) {
+    const { assertCurrent: check, signal } = authority ?? {};
+    if (typeof check !== 'function' ||
+        typeof signal?.aborted !== 'boolean' ||
+        typeof signal.addEventListener !== 'function' ||
+        typeof signal.removeEventListener !== 'function')
+        throw retiredApproval();
+    const assertCurrent = () => {
+        if (signal.aborted)
+            throw retiredApproval();
+        let result;
+        try {
+            result = check();
+        }
+        catch {
+            throw retiredApproval();
+        }
+        if (result !== undefined) {
+            void Promise.resolve(result).catch(() => undefined);
+            throw retiredApproval();
+        }
+        if (signal.aborted)
+            throw retiredApproval();
+    };
+    assertCurrent();
+    return Object.freeze({ assertCurrent, signal });
+}
+//# sourceMappingURL=hardware-transaction-authority.js.map

package/cjs/hardware-transaction-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardware-transaction-authority.js","sourceRoot":"","sources":["../../src/hardware-transaction-authority.ts"],"names":[],"mappings":";;AAYA,kFA4BC;AAnCD,MAAM,eAAe,GAAG,GAAG,EAAE,CAC3B,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,EAAE;IACzE,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,4BAA4B;IAClC,uBAAuB,EAAE,IAAI;CAC9B,CAAC,CAAC;AAEL,SAAgB,mCAAmC,CACjD,SAAuC;IAEvC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,IAAI,EAAE,CAAC;IACzD,IACE,OAAO,KAAK,KAAK,UAAU;QAC3B,OAAO,MAAM,EAAE,OAAO,KAAK,SAAS;QACpC,OAAO,MAAM,CAAC,gBAAgB,KAAK,UAAU;QAC7C,OAAO,MAAM,CAAC,mBAAmB,KAAK,UAAU;QAEhD,MAAM,eAAe,EAAE,CAAC;IAE1B,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,EAAE,CAAC;QAC5C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,KAAK,EAAE,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,eAAe,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,KAAK,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,eAAe,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,EAAE,CAAC;IAC9C,CAAC,CAAC;IACF,aAAa,EAAE,CAAC;IAChB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/cjs/index.js

@@ -14,13 +14,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.descriptorChecksum = exports.deriveDescriptorAddress = exports.invalidateBlockbookAccountCache = exports.PsbtUtils = exports.MAX_PRIVATE_RECORD_LABEL_BYTES = exports.MAX_PRIVATE_RECORD_BYTES = void 0;
+exports.descriptorChecksum = exports.deriveDescriptorAddress = exports.PsbtUtils = exports.MAX_PRIVATE_RECORD_LABEL_BYTES = exports.MAX_PRIVATE_RECORD_BYTES = exports.createKeyringHost = exports.VaultAuthenticationError = void 0;
 __exportStar(require("./transactions"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./storage"), exports);
+var storage_core_1 = require("./storage-core");
+Object.defineProperty(exports, "VaultAuthenticationError", { enumerable: true, get: function () { return storage_core_1.VaultAuthenticationError; } });
 __exportStar(require("./signers"), exports);
 __exportStar(require("./initial-state"), exports);
 __exportStar(require("./keyring-manager"), exports);
+var keyring_host_1 = require("./keyring-host");
+Object.defineProperty(exports, "createKeyringHost", { enumerable: true, get: function () { return keyring_host_1.createKeyringHost; } });
 var private_records_1 = require("./private-records");
 Object.defineProperty(exports, "MAX_PRIVATE_RECORD_BYTES", { enumerable: true, get: function () { return private_records_1.MAX_PRIVATE_RECORD_BYTES; } });
 Object.defineProperty(exports, "MAX_PRIVATE_RECORD_LABEL_BYTES", { enumerable: true, get: function () { return private_records_1.MAX_PRIVATE_RECORD_LABEL_BYTES; } });
@@ -28,11 +31,8 @@ __exportStar(require("./providers"), exports);
 __exportStar(require("./utils/derivation-paths"), exports);
 __exportStar(require("./network-utils"), exports);
 __exportStar(require("./hardware-wallet-manager"), exports);
-__exportStar(require("./hardware-wallet-manager-singleton"), exports);
 var psbt_1 = require("./utils/psbt");
 Object.defineProperty(exports, "PsbtUtils", { enumerable: true, get: function () { return psbt_1.PsbtUtils; } });
-var blockbook_cache_1 = require("./utils/blockbook-cache");
-Object.defineProperty(exports, "invalidateBlockbookAccountCache", { enumerable: true, get: function () { return blockbook_cache_1.invalidateBlockbookAccountCache; } });
 var watch_descriptor_1 = require("./utils/watch-descriptor");
 Object.defineProperty(exports, "deriveDescriptorAddress", { enumerable: true, get: function () { return watch_descriptor_1.deriveDescriptorAddress; } });
 Object.defineProperty(exports, "descriptorChecksum", { enumerable: true, get: function () { return watch_descriptor_1.descriptorChecksum; } });

package/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,0CAAwB;AACxB,4CAA0B;AAC1B,4CAA0B;AAC1B,kDAAgC;AAChC,oDAAkC;AAClC,qDAG2B;AAFzB,2HAAA,wBAAwB,OAAA;AACxB,iIAAA,8BAA8B,OAAA;AAOhC,8CAA4B;AAC5B,2DAAyC;AACzC,kDAAgC;AAChC,4DAA0C;AAC1C,sEAAoD;AACpD,qCAAyC;AAAhC,iGAAA,SAAS,OAAA;AAClB,2DAA0E;AAAjE,kIAAA,+BAA+B,OAAA;AACxC,6DAGkC;AAFhC,2HAAA,uBAAuB,OAAA;AACvB,sHAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,0CAAwB;AACxB,+CAA0D;AAAjD,wHAAA,wBAAwB,OAAA;AACjC,4CAA0B;AAC1B,kDAAgC;AAChC,oDAAkC;AAClC,+CAAmD;AAA1C,iHAAA,iBAAiB,OAAA;AAE1B,qDAG2B;AAFzB,2HAAA,wBAAwB,OAAA;AACxB,iIAAA,8BAA8B,OAAA;AAOhC,8CAA4B;AAC5B,2DAAyC;AACzC,kDAAgC;AAChC,4DAA0C;AAC1C,qCAAyC;AAAhC,iGAAA,SAAS,OAAA;AAClB,6DAGkC;AAFhC,2HAAA,uBAAuB,OAAA;AACvB,sHAAA,kBAAkB,OAAA"}