@sidhujag/sysweb3-keyring 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

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

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"}

package/cjs/keyring-core.js

@@ -59,11 +59,15 @@ const SLH_DSA_PARAMETER_SET = 'SLH-DSA-SHA2-128-24';
 const ethers_v6_1 = require("./ethers-v6");
 const initial_state_1 = require("./initial-state");
 const private_records_1 = require("./private-records");
+const public_bip84_1 = require("./public-bip84");
 const signers_1 = require("./signers");
 const software_hd_account_1 = require("./software-hd-account");
+const software_utxo_account_1 = require("./software-utxo-account");
 const storage_core_1 = require("./storage-core");
+const bip84_native_plan_1 = require("./transactions/bip84-native-plan");
 const ethereum_1 = require("./transactions/ethereum");
 const evm_local_signer_1 = require("./transactions/evm-local-signer");
+const prepared_bip84_1 = require("./transactions/prepared-bip84");
 const prepared_evm_1 = require("./transactions/prepared-evm");
 const syscoin_core_1 = require("./transactions/syscoin-core");
 const types_1 = require("./types");
@@ -1796,6 +1800,228 @@ class KeyringCore {
             return { isValid: false, message: error.message };
         }
     }
+    /** Fixed-profile public UTXO derivation; private material remains operation-local. */
+    async deriveSoftwareBip84HdPublicAccount(input, options) {
+        if (this.bip84Operation)
+            throw new bip84_native_plan_1.Bip84NativeError('BUSY');
+        const operation = {};
+        this.bip84Operation = operation;
+        const nodes = [];
+        try {
+            const session = this.sessionPassword;
+            const mnemonic = this.sessionMnemonic;
+            const revision = this.privateRecordSessionRevision;
+            const vault = this.getVault();
+            const selected = { ...vault.activeAccount };
+            const selectedAccount = vault.accounts[selected.type]?.[selected.id];
+            const identity = {
+                address: selectedAccount?.address,
+                xpub: selectedAccount?.xpub,
+            };
+            const network = { ...vault.activeNetwork };
+            const request = (0, software_utxo_account_1.snapshotBip84HdPublicRequest)(input);
+            const hostGuard = (0, bip84_native_plan_1.snapshotBip84Guard)(options);
+            const profile = (0, bip84_native_plan_1.bip84Profile)(request.network.network);
+            const assertCurrent = () => {
+                const current = this.getVault();
+                const account = current.accounts[selected.type]?.[selected.id];
+                if (!session ||
+                    session.isCleared() ||
+                    this.sessionPassword !== session ||
+                    !mnemonic ||
+                    mnemonic.isCleared() ||
+                    this.sessionMnemonic !== mnemonic ||
+                    this.privateRecordSessionRevision !== revision ||
+                    this.bip84Operation !== operation ||
+                    selected.type !== types_1.KeyringAccountType.HDAccount ||
+                    current.activeAccount.type !== selected.type ||
+                    current.activeAccount.id !== selected.id ||
+                    account?.address !== identity.address ||
+                    account?.xpub !== identity.xpub ||
+                    account?.isLedgerWallet ||
+                    account?.isTrezorWallet ||
+                    account?.isSmartAccount ||
+                    network.kind !== sysweb3_network_1.INetworkType.Syscoin ||
+                    network.chainId !== profile.chainId ||
+                    network.slip44 !== profile.slip44 ||
+                    network.url !== request.network.endpoint ||
+                    current.activeNetwork.kind !== network.kind ||
+                    current.activeNetwork.chainId !== network.chainId ||
+                    current.activeNetwork.slip44 !== network.slip44 ||
+                    current.activeNetwork.url !== network.url)
+                    throw new bip84_native_plan_1.Bip84NativeError('CANCELLED');
+            };
+            const guard = () => {
+                assertCurrent();
+                hostGuard();
+                assertCurrent();
+            };
+            guard();
+            const config = (0, sysweb3_network_1.getNetworkConfig)(profile.slip44, profile.currency);
+            const { hd } = (0, signers_1.getSyscoinSigners)({
+                mnemonic: this.getDecryptedMnemonic(),
+                rpc: {
+                    formattedNetwork: { ...network, currency: profile.currency },
+                    networkConfig: {
+                        networks: config.networks,
+                        types: {
+                            xPubType: config.types.xPubType,
+                            zPubType: config.types.zPubType,
+                        },
+                    },
+                },
+            });
+            let node = hd.getRootNode();
+            nodes.push(node);
+            for (const child of [84, profile.slip44, request.accountIndex]) {
+                node = node.deriveHardened(child);
+                nodes.push(node);
+                if (node.index !== child + 0x80000000)
+                    throw new bip84_native_plan_1.Bip84NativeError('ACCOUNT_MISMATCH');
+            }
+            const account = (0, public_bip84_1.parseBip84PublicAccount)({
+                network: request.network.network,
+                accountKey: node.neutered().toBase58(),
+            });
+            if (account.accountIndex !== request.accountIndex)
+                throw new bip84_native_plan_1.Bip84NativeError('ACCOUNT_MISMATCH');
+            const receive = (0, public_bip84_1.deriveBip84PublicAddress)({
+                network: request.network.network,
+                accountKey: account.canonicalKey,
+                branch: 0,
+                index: 0,
+            });
+            guard();
+            return Object.freeze({
+                type: 'HDAccount',
+                accountIndex: request.accountIndex,
+                account,
+                receive,
+            });
+        }
+        catch (error) {
+            if (error instanceof bip84_native_plan_1.Bip84NativeError)
+                throw error;
+            throw new bip84_native_plan_1.Bip84NativeError('INVALID_REQUEST');
+        }
+        finally {
+            // Only buffers owned by this operation; library/JS copies are not claimed zeroized.
+            for (const node of nodes)
+                node.privateKey?.fill(0);
+            if (this.bip84Operation === operation)
+                this.bip84Operation = undefined;
+        }
+    }
+    /** Fixed selected-account native signing. No storage, discovery or broadcast. */
+    async signPreparedSoftwareBip84Transaction(input, options) {
+        if (this.bip84Operation)
+            throw new bip84_native_plan_1.Bip84NativeError('BUSY');
+        const operation = {};
+        this.bip84Operation = operation;
+        const nodes = [];
+        try {
+            const session = this.sessionPassword;
+            const mnemonic = this.sessionMnemonic;
+            const revision = this.privateRecordSessionRevision;
+            const vault = this.getVault();
+            const selected = { ...vault.activeAccount };
+            const selectedAccount = vault.accounts[selected.type]?.[selected.id];
+            const identity = {
+                id: selectedAccount?.id,
+                address: selectedAccount?.address,
+                xpub: selectedAccount?.xpub,
+            };
+            const network = { ...vault.activeNetwork };
+            const { account, validated } = (0, prepared_bip84_1.snapshotPreparedBip84Request)(input);
+            const hostGuard = (0, bip84_native_plan_1.snapshotBip84Guard)(options);
+            const profile = (0, bip84_native_plan_1.bip84Profile)(validated.prepared.plan.network.network);
+            const assertCurrent = () => {
+                const current = this.getVault();
+                const active = current.accounts[selected.type]?.[selected.id];
+                if (!session ||
+                    session.isCleared() ||
+                    this.sessionPassword !== session ||
+                    !mnemonic ||
+                    mnemonic.isCleared() ||
+                    this.sessionMnemonic !== mnemonic ||
+                    this.privateRecordSessionRevision !== revision ||
+                    this.bip84Operation !== operation ||
+                    selected.type !== types_1.KeyringAccountType.HDAccount ||
+                    selected.id !== account.index ||
+                    current.activeAccount.type !== selected.type ||
+                    current.activeAccount.id !== selected.id ||
+                    !active ||
+                    active.id !== account.index ||
+                    active.id !== identity.id ||
+                    active.address !== identity.address ||
+                    active.xpub !== identity.xpub ||
+                    active.isImported ||
+                    active.isLedgerWallet ||
+                    active.isTrezorWallet ||
+                    active.isSmartAccount ||
+                    network.kind !== sysweb3_network_1.INetworkType.Syscoin ||
+                    network.chainId !== profile.chainId ||
+                    network.slip44 !== profile.slip44 ||
+                    network.url !== validated.prepared.plan.network.endpoint ||
+                    current.activeNetwork.kind !== network.kind ||
+                    current.activeNetwork.chainId !== network.chainId ||
+                    current.activeNetwork.slip44 !== network.slip44 ||
+                    current.activeNetwork.url !== network.url)
+                    throw new bip84_native_plan_1.Bip84NativeError('CANCELLED');
+            };
+            const guard = () => {
+                assertCurrent();
+                hostGuard();
+                assertCurrent();
+            };
+            guard();
+            if (typeof identity.xpub !== 'string' ||
+                (0, public_bip84_1.parseBip84PublicAccount)({
+                    network: validated.prepared.plan.network.network,
+                    accountKey: identity.xpub,
+                }).canonicalKey !== account.expectedAccountKey)
+                throw new bip84_native_plan_1.Bip84NativeError('ACCOUNT_MISMATCH');
+            const words = this.getDecryptedMnemonic();
+            if (!BIP84.validateMnemonic(words))
+                throw new bip84_native_plan_1.Bip84NativeError('ACCOUNT_MISMATCH');
+            guard();
+            const config = (0, sysweb3_network_1.getNetworkConfig)(profile.slip44, profile.currency);
+            const { hd } = (0, signers_1.getSyscoinSigners)({
+                mnemonic: words,
+                rpc: {
+                    formattedNetwork: { ...network, currency: profile.currency },
+                    networkConfig: {
+                        networks: config.networks,
+                        types: {
+                            xPubType: config.types.xPubType,
+                            zPubType: config.types.zPubType,
+                        },
+                    },
+                },
+            });
+            let node = hd.getRootNode();
+            nodes.push(node);
+            for (const child of [84, profile.slip44, account.index]) {
+                guard();
+                node = node.deriveHardened(child);
+                nodes.push(node);
+                if (node.index !== child + 0x80000000)
+                    throw new bip84_native_plan_1.Bip84NativeError('ACCOUNT_MISMATCH');
+            }
+            guard();
+            return (0, prepared_bip84_1.signValidatedBip84Plan)(validated, node, guard);
+        }
+        catch (error) {
+            if (error instanceof bip84_native_plan_1.Bip84NativeError)
+                throw error;
+            throw new bip84_native_plan_1.Bip84NativeError('INVALID_REQUEST');
+        }
+        finally {
+            (0, prepared_bip84_1.clearBip84PrivateNodes)(nodes);
+            if (this.bip84Operation === operation)
+                this.bip84Operation = undefined;
+        }
+    }
     /** Fixed-path derivation for an authenticated software host; no persistence. */
     async deriveSoftwareEvmHdRuntimeAccount(input, options) {
         // Capture the session and selection before inspecting caller-owned objects.