@sidhujag/sysweb3-keyring 1.0.628 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 2.1.0
+
+- Add the standalone `cjs/public-bip84` entry for strict Bitcoin/Syscoin mainnet account parsing and native SegWit address derivation. It returns public data only; an account public key does not prove ancestry or ownership.
+- Add `SoftwareKeyring.deriveBip84HdPublicAccount` for guarded public derivation from an unlocked software HD wallet, without selecting accounts, writing storage or discovering addresses.
+- Add the standalone `cjs/bip84-native` planner for bounded native-coin P2WPKH transactions with explicit parent data, change, RBF and exact fee limits. Asset, special and coinbase parents are excluded.
+- Add `SoftwareKeyring.signPreparedBip84Transaction` for the selected Bitcoin/Syscoin mainnet HD account. It binds the account, network and synchronous host guard, verifies the rebuilt transaction and signatures, and returns immutable signed bytes, identifiers and exact fee/size data.
+- These offline APIs do not unlock, access a provider, persist records or broadcast. Hosts still own input eligibility, fresh approval, change reservations and durable journaling before broadcast. Existing vault, EVM, generic PSBT and hardware APIs remain unchanged; native and live qualification remain separate.
+
+## 2.0.0
+
+- Add `SoftwareKeyring.deriveEvmHdRuntimeAccount` for host-allocated Ethereum BIP44 indices. It returns the existing password-encrypted runtime account record without installing an account, writing storage or querying a network. The method binds session, selection and network identity and requires a synchronous host guard. Hosts must strip encrypted `xprv` before producing public metadata.
+
+- Add `SoftwareKeyring.signPreparedEvmTransaction` for offline signing of fully specified legacy/EIP-1559 envelopes. The request binds the selected software account and exact network/endpoint, requires synchronous host admission, validates all signed fields and recovered identity, and returns immutable signed bytes plus their local hash. It never estimates fees, resolves names, fills fields or broadcasts; hosts must durably retain the result before submission and reconcile uncertain broadcasts by hash.
+
+- Breaking: Ledger signing requires an explicitly injected semantic `LedgerHost`. Raw LedgerJS transports/clients are removed; use the isolated browser ESM host entry for device access.
+- Adopt current Device Management Kit and Ethereum signer packages while preserving the custom Syscoin/Bitcoin protocol. Serialize device operations and reject stale, wrong-account, malformed and mismatched-sighash responses.
+- Disable remote Ledger metadata/transaction checks/telemetry by default. Require fresh per-intent consent for transaction/typed-data signing that may fall back to blind signing.
+- Bind receive addresses to public account derivation, preserve on-device approval for unusual paths, and snapshot queued UTXO requests before connection awaits.
+- Existing software-only entry, vault formats and account derivation remain compatible. Host/device and native-runtime qualification are separate requirements.
+
+- Remove the legacy Trezor UTXO library. Reuse Bitcoinjs address decoding with a checksum-verified two-byte-version compatibility path, and encode witness vectors with the public CompactSize codec.
+
+- Move Trezor hardware integration to Connect 10.0.1 and remove the redundant direct Connect Web dependency.
+- Load the browser transport only inside a supported MV3 extension. Preserve CommonJS/ESM and software-entry imports without browser globals or device initialization.
+- Preserve the existing SDK failure payload while retaining Connect error codes; stop retrying cancellations, disconnects and unsupported hosts/coins.
+- Replace removed Connect device events with status updates from request outcomes and disposal. Immediate physical unplug notifications are no longer exposed by upstream.
+- Reject pending calls locally on lock/disposal and discard late responses. Defer remote cleanup while requests are outstanding; return `HARDWARE_SIGNER_BUSY` until they settle rather than opening another approval prompt.
+- Normalize Trezor hexadecimal recovery values without mutating signed responses; preserve approved transaction and session checks.
+- Physical device qualification and consuming-extension Suite Web permissions remain release gates.
+
 ## 1.0.628
 
 - Add the `cjs/software` entry with explicit asynchronous host storage and an opaque wallet-authority handle. Software keyrings do not load browser hardware transports or global storage.

package/README.md

@@ -74,6 +74,114 @@ const keyringManager = await KeyringManager.createInitialized(
 );
 ```
 
+### Offline BIP84 public account derivation
+
+The standalone public entry accepts a bare **mainnet xpub or zpub** for a depth-3
+account whose child number is hardened. It derives only native SegWit P2WPKH
+addresses at `/0/index` (receive) or `/1/index` (change), with a nonhardened index
+from 0 through 2,147,483,647. Choose `bitcoin` or `syscoin` explicitly. Testnet
+versions, private keys, descriptors, origin/path suffixes and arbitrary networks
+are rejected. Requests must be plain own-data objects with exactly the documented
+fields; inherited properties, getters and extra fields are rejected. Existing
+generic watch-descriptor and keyring APIs are unchanged.
+
+```typescript
+import {
+  parseBip84PublicAccount,
+  deriveBip84PublicAddress,
+} from '@sidhujag/sysweb3-keyring/cjs/public-bip84';
+
+const account = parseBip84PublicAccount({
+  network: 'syscoin',
+  accountKey: exportedPublicAccountKey,
+});
+const receive = deriveBip84PublicAddress({
+  network: account.network,
+  accountKey: account.canonicalKey,
+  branch: 0,
+  index: 0,
+});
+// receive.address, receive.scriptPubKey; no keyring or provider required.
+```
+
+The canonical account identity is the tuple `(network, policy, canonicalKey)`.
+`policy` is `bip84-p2wpkh`; `canonicalKey` normalizes xpub/zpub aliases to zpub.
+`accountIndex` is the encoded hardened child number minus 2^31. Key serialization
+and depth cannot prove the original purpose, coin type, full ancestry or ownership.
+In particular, the same public key can be encoded for either supported network;
+network selection changes the address encoding and identity, not the derived
+witness program. Require the user to verify their source wallet's BIP84 account
+and network, and compare a known receive address before using a watch account.
+
+Calls are synchronous and stateless: one key of at most 112 Base58 characters,
+one account parse and two requested child derivations per address; no range scan,
+cache, fetch, storage, RNG or wallet signing. The upstream BIP32 factory runs
+deterministic ECC known-vector self-tests at module initialization (including
+fixed-fixture signatures); it never receives a wallet private key here. The
+underlying BIP32 implementation can retry an invalid child internally; a returned index mismatch is rejected instead
+of silently changing the requested path. There is no wall-clock guarantee for
+pathological library retries. Successful outputs are frozen objects containing
+only strings and numbers (including a frozen nested account), never a BIP32 node.
+Invalid input throws `PublicBip84Error` with a constant `INVALID_INPUT`,
+`INVALID_ACCOUNT` or `INVALID_DERIVATION` code and no echoed key.
+
+An account public key reveals all nonhardened receive and change addresses and
+allows their activity to be linked. It cannot spend funds on its own, but remains
+privacy-sensitive. The API performs no discovery or history lookup. A consuming
+wallet must obtain informed consent before sharing an account key or derived
+addresses with an indexer, own explicit discovery/page/concurrency bounds, and
+label partial or unavailable history honestly. This library slice does not
+implement or qualify a complete mobile watch-account feature.
+
+### Development BIP84 native-transfer foundation
+
+`SoftwareKeyring.deriveBip84HdPublicAccount(request, { assertCurrent })` derives
+an explicit HD index for a captured Bitcoin/Syscoin mainnet context and returns
+only frozen public account and receive-address data. It requires an already
+unlocked software host; it does not select accounts, update a catalogue, store an
+xprv, discover addresses or contact a provider. The host must supply a synchronous
+revision/consent guard and recheck it after awaiting the operation. Labels and
+currency strings do not choose the derivation path.
+
+The standalone `@sidhujag/sysweb3-keyring/cjs/bip84-native` entry exports
+`prepareBip84NativeTransaction` and its types. It builds exact unsigned version-2
+bytes from a bounded immutable plan: one P2WPKH recipient, optional verified
+branch-1 change, explicit RBF, locktime zero, full previous transaction data and
+integer fee limits. Parent transactions must be ordinary version 1/2 and
+non-coinbase. All SYS special/asset parents are excluded even when a selected
+output appears to be native change. Missing provider asset metadata is not proof
+that an output is safe to spend.
+
+The planner allows at most 64 inputs/parents, 1,000,000 bytes per parent and
+2,000,000 aggregate parent bytes. Before decoding any parent, it also enforces
+an aggregate budget of 8,192 decoded components: parent inputs, outputs, witness
+vectors and witness items each consume one component, including empty items.
+This is a wallet resource policy, not a consensus limit; large scripts remain
+subject to the separate byte limits. Wallet policy additionally caps absolute fees
+at 10,000,000 satoshis and fee rate at 1,000 sat/vB; callers must provide limits
+no higher than those ceilings. Maximum signature size is used only to reject
+fees that cannot possibly satisfy the rate ceiling; the prepared signer checks
+that ceiling again using the actual finalized virtual size. Zero fee is arithmetic-valid, not a relay guarantee.
+Oversized valid parents are unavailable to this initial planner; no data is
+truncated or silently omitted. Returned bytes/data are public and privacy-sensitive.
+
+This is a development foundation, **not a native UTXO sending capability**.
+`SoftwareKeyring.signPreparedBip84Transaction(request, { assertCurrent })` (added in 2.1.0)
+signs only the selected HD account's exact prepared plan. It requires the SDK
+selected type/index, requested account and seed-derived canonical public key to
+agree. The mandatory synchronous host guard additionally binds fresh approval,
+monotonic revision and review expiry. It rebuilds the plan, verifies complete
+low-S SIGHASH_ALL signatures and exact unsigned bytes, and checks the final fee
+against actual virtual size. It performs no unlock, storage, discovery or
+broadcast and returns only frozen signed bytes, identifiers and fee/size data.
+It does not consume or create per-account encrypted xprvs. The host still owns
+canonical-chain/unspent checks, confirmed-input eligibility, protected collateral
+and pending outpoint reservations, change-index persistence, fresh authentication,
+review cancellation and eventual journal-before-broadcast behavior. Full parent
+bytes prove an outpoint's content, not chain membership, maturity or spendability.
+Existing generic PSBT, EVM and hardware APIs are unchanged. Native and live
+qualification remain future work.
+
 ### Account Management
 
 ```javascript
@@ -150,6 +258,32 @@ const signature = await keyringManager.ethereumTransaction.signPersonalMessage([
 
 ### Hardware Wallet Support
 
+Trezor uses `@trezor/connect-webextension` 10.0.1. The hardware adapter loads it
+only when a supported MV3 extension invokes Trezor; ordinary Node CommonJS/ESM
+imports and the software entry do not initialize browser transports. Unsupported
+hosts reject hardware operations instead of falling back to software signing.
+
+The extension must configure `externally_connectable` for
+`https://suite.trezor.io/*` and host access to that origin, as required by the
+[published Connect 10 webextension package](https://www.npmjs.com/package/@trezor/connect-webextension/v/10.0.1).
+Connect selects Suite Desktop or the Suite Web popup. The old Connect 9 iframe,
+content script, and `connectSrc` settings are not part of this integration.
+
+Connect 10 does not expose the old device event emitter. SDK connection status
+and cached model information update from request results and disposal; they are
+not immediate physical unplug notifications. Disposal immediately rejects pending
+SDK operations and fences late replies. Suite Web may leave its popup open; a
+late approval there is discarded locally rather than treated as a fresh approval.
+When an underlying request is still active, transport cleanup is deferred to avoid
+triggering an automatic fallback popup. New initialization fails with
+`HARDWARE_SIGNER_BUSY` until that request settles; local lock/disposal does not
+wait for the remote prompt. An upstream transport failure can still trigger remote
+fallback UI while that old request is pending; the local SDK will reject its result.
+A failed or cancelled operation
+never authorizes a cached transaction, and terminal disconnect/unsupported-host
+errors are not retried. Device pairing, display verification, signing, and
+reconnection still require physical-device qualification in the consuming host.
+
 ```javascript
 // Import Trezor account
 const trezorAccount = await keyringManager.importTrezorAccount(
@@ -293,3 +427,43 @@ collection rather than guaranteed memory erasure.
 ## License
 
 MIT License
+
+### Ledger platform host
+
+Ledger device access uses the Device Management Kit. The regular and software
+entries do not load a Ledger transport or device SDK. Browser integrations must
+create the heavy host from `@sidhujag/sysweb3-keyring/esm/ledger-host` in a visible
+extension page and inject its semantic `LedgerHost` port into the wallet authority:
+
+```ts
+// Visible device page only:
+import { createLedgerDmkHost } from '@sidhujag/sysweb3-keyring/esm/ledger-host';
+const host = createLedgerDmkHost({
+  confirmBlindSigning: async (intent, signal) => {
+    // Show the exact immutable intent and an explicit blind-signing warning.
+    // Return true only after a fresh user decision; cancellation must return false.
+    return showTrustedWalletConfirmation(intent, signal);
+  },
+});
+
+// Wallet authority: use a secured semantic port to that page, not a raw APDU port.
+const wallet = new KeyringManager(undefined, authorizedLedgerHostPort);
+```
+
+Use only the ESM host entry with a browser bundler and its required platform
+polyfills. `cjs/ledger-host` is not a supported entry. A service worker cannot own
+the WebHID device picker. The platform must bind the host to its own trusted page,
+revoke pending operations on lock/close, and never expose this port to dapps.
+A missing host fails with `HARDWARE_SIGNER_UNAVAILABLE`; there is no legacy
+LedgerJS fallback. Pass either a shared hardware manager or a Ledger host to
+`KeyringManager`, not both.
+
+The default host performs no remote metadata lookup, transaction checks, or
+signing telemetry. The current Ethereum signer library can fall back to blind
+signing, so transaction and typed-data signing require per-request approval
+through the trusted `confirmBlindSigning` callback. Omitting it fails closed.
+Personal-message signing and address retrieval remain available offline.
+Signatures are checked against the expected account; UTXO signatures must also
+match the approved PSBT and its requested sighash coverage. The custom UTXO host
+supports the existing Syscoin and Bitcoin app protocols. Physical-device and
+firmware qualification remain separate from source and mocked-device tests.

package/cjs/bip84-native.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareBip84NativeTransaction = exports.Bip84NativeError = void 0;
+/** Pure native-coin BIP84 transfer preparation, without a wallet or provider. */
+var bip84_native_plan_1 = require("./transactions/bip84-native-plan");
+Object.defineProperty(exports, "Bip84NativeError", { enumerable: true, get: function () { return bip84_native_plan_1.Bip84NativeError; } });
+Object.defineProperty(exports, "prepareBip84NativeTransaction", { enumerable: true, get: function () { return bip84_native_plan_1.prepareBip84NativeTransaction; } });
+//# sourceMappingURL=bip84-native.js.map

package/cjs/bip84-native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip84-native.js","sourceRoot":"","sources":["../../src/bip84-native.ts"],"names":[],"mappings":";;;AAAA,iFAAiF;AACjF,sEAG0C;AAFxC,qHAAA,gBAAgB,OAAA;AAChB,kIAAA,6BAA6B,OAAA"}