@sidhujag/sysweb3-keyring 1.0.491

package/types/keyring-manager.d.ts

@@ -0,0 +1,184 @@
+import { INetwork, INetworkType } from '@sidhujag/sysweb3-network';
+import { ethers } from 'ethers';
+import { LedgerKeyring } from './ledger';
+import { SyscoinHDSigner } from './signers';
+import { TrezorKeyring } from './trezor';
+import { IKeyringAccountState, ISyscoinTransactions, KeyringAccountType, IEthereumTransactions, IKeyringManager } from './types';
+export interface ISysAccount {
+    address: string;
+    label?: string;
+    xprv?: string;
+    xpub: string;
+}
+/**
+ * Secure Buffer implementation for sensitive data
+ * Provides explicit memory clearing capability
+ */
+declare class SecureBuffer {
+    private buffer;
+    private _isCleared;
+    constructor(data: string | Buffer);
+    get(): Buffer;
+    toString(): string;
+    clear(): void;
+    isCleared(): boolean;
+}
+export declare class KeyringManager implements IKeyringManager {
+    trezorSigner: TrezorKeyring;
+    ledgerSigner: LedgerKeyring;
+    initialTrezorAccountState: IKeyringAccountState;
+    initialLedgerAccountState: IKeyringAccountState;
+    utf8Error: boolean;
+    ethereumTransaction: IEthereumTransactions;
+    syscoinTransaction: ISyscoinTransactions;
+    private storage;
+    private getVaultState;
+    setVaultStateGetter: (getter: () => any) => void;
+    private getVault;
+    private getActiveChain;
+    private sessionPassword;
+    private sessionMnemonic;
+    constructor();
+    static createInitialized(seed: string, password: string, vaultStateGetter: () => any): Promise<KeyringManager>;
+    initialize(seed: string, password: string, network?: INetwork): Promise<IKeyringAccountState>;
+    setStorage: (client: any) => any;
+    validateAccountType: (account: IKeyringAccountState) => KeyringAccountType.HDAccount | KeyringAccountType.Imported;
+    isUnlocked: () => boolean;
+    lockWallet: () => void;
+    transferSessionTo: (targetKeyring: IKeyringManager) => void;
+    receiveSessionOwnership: (sessionPassword: SecureBuffer, sessionMnemonic: SecureBuffer) => void;
+    addNewAccount: (label?: string) => Promise<IKeyringAccountState>;
+    unlock(password: string): Promise<{
+        canLogin: boolean;
+        needsAccountCreation?: boolean;
+    }>;
+    getNewChangeAddress: () => Promise<string>;
+    getChangeAddress: (id: number) => Promise<string>;
+    getPubkey: (id: number, isChangeAddress: boolean) => Promise<string>;
+    getBip32Path: (id: number, isChangeAddress: boolean) => Promise<string>;
+    updateReceivingAddress: () => Promise<string>;
+    getAccountById: (id: number, accountType: KeyringAccountType) => Omit<IKeyringAccountState, "xprv">;
+    getPrivateKeyByAccountId: (id: number, accountType: KeyringAccountType, pwd: string) => Promise<string>;
+    getActiveAccount: () => {
+        activeAccount: Omit<IKeyringAccountState, "xprv">;
+        activeAccountType: KeyringAccountType;
+    };
+    getEncryptedXprv: (hd: SyscoinHDSigner) => string;
+    getSeed: (pwd: string) => Promise<any>;
+    setSignerNetwork: (network: INetwork) => Promise<{
+        activeChain?: INetworkType;
+        success: boolean;
+    }>;
+    forgetMainWallet: (pwd: string) => Promise<void>;
+    importWeb3Account: (mnemonicOrPrivKey: string) => ethers.Wallet;
+    getAccountXpub: () => string;
+    isSeedValid: (seedPhrase: string) => boolean;
+    createNewSeed: () => string;
+    getUTXOState: () => any;
+    importTrezorAccount(label?: string): Promise<IKeyringAccountState>;
+    importLedgerAccount(label?: string): Promise<IKeyringAccountState>;
+    getActiveUTXOAccountState: () => any;
+    getNetwork: () => any;
+    createEthAccount: (privateKey: string) => ethers.Wallet;
+    private fetchCurrentAccountData;
+    getAddress: (xpub: string, isChangeAddress: boolean) => Promise<string>;
+    getCurrentAddressPubkey: (xpub: string, isChangeAddress: boolean) => Promise<string>;
+    getCurrentAddressBip32Path: (xpub: string, isChangeAddress: boolean) => Promise<string>;
+    logout: () => void;
+    importAccount(privKey: string, label?: string): Promise<IKeyringAccountState>;
+    validateZprv(zprv: string, targetNetwork?: INetwork): {
+        isValid: boolean;
+        node: any;
+        network: {
+            bip32: {
+                public: number;
+                private: number;
+            };
+            messagePrefix: string;
+            bech32: string;
+            pubKeyHash: any;
+            scriptHash: any;
+            slip44: any;
+            wif: any;
+        };
+        message: string;
+    } | {
+        isValid: boolean;
+        message: any;
+        node?: undefined;
+        network?: undefined;
+    };
+    /**
+     * PRIVATE METHODS
+     */
+    private getDecryptedPrivateKey;
+    private getSigner;
+    private getReadOnlySigner;
+    private validateAndHandleErrorByMessage;
+    private getAccountsState;
+    /**
+     *
+     * @param password
+     * @param salt
+     * @returns hash: string
+     */
+    private encryptSHA512;
+    private getSysActivePrivateKey;
+    private getInitialAccountData;
+    private _createTrezorAccount;
+    private _createLedgerAccount;
+    private getFormattedBackendAccount;
+    private setLatestIndexesFromXPubTokens;
+    private createUTXOAccountAtIndex;
+    private addNewAccountToSyscoinChain;
+    private addNewAccountToEth;
+    private getNextAccountId;
+    private getBasicWeb3AccountInfo;
+    private setDerivedWeb3Accounts;
+    private setSignerEVM;
+    private clearTemporaryLocalKeys;
+    private recreateSessionFromVault;
+    private _getPrivateKeyAccountInfos;
+    /**
+     * Common method to decrypt mnemonic from session
+     * Eliminates code duplication across multiple methods
+     */
+    private getDecryptedMnemonic;
+    /**
+     * Creates network RPC config from current active network without making RPC calls
+     * Common utility for all on-demand signer creation
+     */
+    private createNetworkRpcConfig;
+    /**
+     * Common signer creation logic - takes decrypted mnemonic/zprv and creates fresh signer
+     * OPTIMIZED: No RPC call needed - uses network config directly
+     */
+    private createFreshUTXOSigner;
+    /**
+     * Creates a fresh UTXO signer for HD accounts derived from the main seed
+     * OPTIMIZED: No RPC call needed - uses network config directly
+     */
+    private createOnDemandUTXOSigner;
+    /**
+     * Creates a fresh UTXO signer for imported accounts from stored zprv
+     * OPTIMIZED: No RPC call needed - uses network config directly
+     */
+    private createOnDemandUTXOSignerFromImported;
+    /**
+     * Common method to create on-demand signer for active account
+     * Handles account type determination and delegates to appropriate method
+     */
+    private createOnDemandSignerForActiveAccount;
+    private isZprv;
+    initializeSession: (seedPhrase: string, password: string) => Promise<void>;
+    createFirstAccount: (label?: string) => Promise<IKeyringAccountState>;
+    initializeWalletSecurely: (seedPhrase: string, password: string) => Promise<IKeyringAccountState>;
+    private getSessionPasswordString;
+    private getSessionMnemonicString;
+    private generateNetworkAwareLabel;
+    /**
+     * Clean up all resources
+     */
+    destroy(): Promise<void>;
+}
+export {};

package/types/ledger/bitcoin_client/index.d.ts

@@ -0,0 +1,5 @@
+import AppClient, { PartialSignature } from './lib/appClient';
+import { DefaultDescriptorTemplate, DefaultWalletPolicy, WalletPolicy } from './lib/policy';
+import { PsbtV2 } from './lib/psbtv2';
+export { AppClient, PsbtV2, DefaultDescriptorTemplate, DefaultWalletPolicy, PartialSignature, WalletPolicy, };
+export default AppClient;

package/types/ledger/bitcoin_client/lib/appClient.d.ts

@@ -0,0 +1,106 @@
+import Transport from '@ledgerhq/hw-transport';
+import { WalletPolicy } from './policy';
+import { PsbtV2 } from './psbtv2';
+/**
+ * This class represents a partial signature produced by the app during signing.
+ * It always contains the `signature` and the corresponding `pubkey` whose private key
+ * was used for signing; in the case of taproot script paths, it also contains the
+ * tapleaf hash.
+ */
+export declare class PartialSignature {
+    readonly pubkey: Buffer;
+    readonly signature: Buffer;
+    readonly tapleafHash?: Buffer;
+    constructor(pubkey: Buffer, signature: Buffer, tapleafHash?: Buffer);
+}
+/**
+ * This class encapsulates the APDU protocol documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md
+ */
+export declare class AppClient {
+    readonly transport: Transport;
+    constructor(transport: Transport);
+    private makeRequest;
+    /**
+     * Returns an object containing the currently running app's name, version and the device status flags.
+     *
+     * @returns an object with app name, version and device status flags.
+     */
+    getAppAndVersion(): Promise<{
+        flags: number | Buffer;
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Requests the BIP-32 extended pubkey to the hardware wallet.
+     * If `display` is `false`, only standard paths will be accepted; an error is returned if an unusual path is
+     * requested.
+     * If `display` is `true`, the requested path is shown on screen for user verification; unusual paths can be
+     * requested, and a warning is shown to the user in that case.
+     *
+     * @param path the requested BIP-32 path as a string
+     * @param display `false` to silently retrieve a pubkey for a standard path, `true` to display the path on screen
+     * @returns the base58-encoded serialized extended pubkey (xpub)
+     */
+    getExtendedPubkey(path: string, display?: boolean): Promise<string>;
+    /**
+     * Registers a `WalletPolicy`, after interactive verification from the user.
+     * On success, after user's approval, this function returns the id (which is the same that can be computed with
+     * `walletPolicy.getid()`), followed by the 32-byte hmac. The client should store the hmac to use it for future
+     * requests to `getWalletAddress` or `signPsbt` using this `WalletPolicy`.
+     *
+     * @param walletPolicy the `WalletPolicy` to register
+     * @returns a pair of two 32-byte arrays: the id of the Wallet Policy, followed by the policy hmac
+     */
+    registerWallet(walletPolicy: WalletPolicy): Promise<readonly [Buffer, Buffer]>;
+    /**
+     * Returns the address of `walletPolicy` for the given `change` and `addressIndex`.
+     *
+     * @param walletPolicy the `WalletPolicy` to use
+     * @param walletHMAC the 32-byte hmac returned during wallet registration for a registered policy; otherwise
+     * `null` for a standard policy
+     * @param change `0` for a normal receive address, `1` for a change address
+     * @param addressIndex the address index to retrieve
+     * @param display `True` to show the address on screen, `False` to retrieve it silently
+     * @returns the address, as an ascii string.
+     */
+    getWalletAddress(walletPolicy: WalletPolicy, walletHMAC: Buffer | null, change: number, addressIndex: number, display: boolean): Promise<string>;
+    /**
+     * Signs a psbt using a (standard or registered) `WalletPolicy`. This is an interactive command, as user validation
+     * is necessary using the device's secure screen.
+     * On success, a map of input indexes and signatures is returned.
+     * @param psbt a base64-encoded string, or a psbt in a binary Buffer. Using the `PsbtV2` type is deprecated.
+     * @param walletPolicy the `WalletPolicy` to use for signing
+     * @param walletHMAC the 32-byte hmac obtained during wallet policy registration, or `null` for a standard policy
+     * @param progressCallback optionally, a callback that will be called every time a signature is produced during
+     * the signing process. The callback does not receive any argument, but can be used to track progress.
+     * @returns an array of of tuples with 2 elements containing:
+     *    - the index of the input being signed;
+     *    - an instance of PartialSignature
+     */
+    signPsbt(psbt: PsbtV2 | string | Buffer, walletPolicy: WalletPolicy, walletHMAC: Buffer | null, progressCallback?: () => void): Promise<[number, PartialSignature][]>;
+    /**
+     * Returns the fingerprint of the master public key, as per BIP-32 standard.
+     * @returns the master key fingerprint as a string of 8 hexadecimal digits.
+     */
+    getMasterFingerprint(): Promise<string>;
+    /**
+     * Signs a message using the legacy Bitcoin Message Signing standard. The signed message is
+     * the double-sha256 hash of the concatenation of:
+     * - "\x18Bitcoin Signed Message:\n";
+     * - the length of `message`, encoded as a Bitcoin-style variable length integer;
+     * - `message`.
+     *
+     * @param message the serialized message to sign
+     * @param path the BIP-32 path of the key used to sign the message
+     * @returns base64-encoded signature of the message.
+     */
+    signMessage(message: Buffer, path: string): Promise<string>;
+    private validateAddress;
+    /**
+     * Maps Ledger app names to network configurations
+     * This allows support for multiple UTXO networks beyond just Syscoin
+     */
+    private getNetworkFromAppName;
+}
+export default AppClient;

package/types/ledger/bitcoin_client/lib/bip32.d.ts

@@ -0,0 +1,11 @@
+export declare function pathElementsToBuffer(paths: readonly number[]): Buffer;
+export declare function bip32asBuffer(path: string): Buffer;
+export declare function pathArrayToString(pathElements: readonly number[]): string;
+export declare function pathStringToArray(path: string): readonly number[];
+export declare function pubkeyFromXpub(xpub: string): Buffer;
+export declare function getXpubComponents(xpub: string): {
+    readonly chaincode: Buffer;
+    readonly pubkey: Buffer;
+    readonly version: number;
+};
+export declare function hardenedPathOf(pathElements: readonly number[]): readonly number[];

package/types/ledger/bitcoin_client/lib/buffertools.d.ts

@@ -0,0 +1,28 @@
+export declare function unsafeTo64bitLE(n: number): Buffer;
+export declare function unsafeFrom64bitLE(byteArray: Buffer): number;
+export declare class BufferWriter {
+    private bufs;
+    write(alloc: number, fn: (b: Buffer) => void): void;
+    writeUInt8(i: number): void;
+    writeInt32(i: number): void;
+    writeUInt32(i: number): void;
+    writeUInt64(i: number): void;
+    writeVarInt(i: number): void;
+    writeSlice(slice: Buffer): void;
+    writeVarSlice(slice: Buffer): void;
+    buffer(): Buffer;
+}
+export declare class BufferReader {
+    readonly buffer: Buffer;
+    offset: number;
+    constructor(buffer: Buffer, offset?: number);
+    available(): number;
+    readUInt8(): number;
+    readInt32(): number;
+    readUInt32(): number;
+    readUInt64(): number;
+    readVarInt(): bigint;
+    readSlice(n: number): Buffer;
+    readVarSlice(): Buffer;
+    readVector(): readonly Buffer[];
+}

package/types/ledger/bitcoin_client/lib/clientCommands.d.ts

@@ -0,0 +1,77 @@
+import { Merkle } from './merkle';
+import { MerkleMap } from './merkleMap';
+import { WalletPolicy } from './policy';
+declare enum ClientCommandCode {
+    YIELD = 16,
+    GET_PREIMAGE = 64,
+    GET_MERKLE_LEAF_PROOF = 65,
+    GET_MERKLE_LEAF_INDEX = 66,
+    GET_MORE_ELEMENTS = 160
+}
+declare abstract class ClientCommand {
+    abstract code: ClientCommandCode;
+    abstract execute(request: Buffer): Buffer;
+}
+export declare class YieldCommand extends ClientCommand {
+    private readonly progressCallback?;
+    private results;
+    readonly code = ClientCommandCode.YIELD;
+    constructor(results: Buffer[], progressCallback?: (() => void) | undefined);
+    execute(request: Buffer): Buffer;
+}
+export declare class GetPreimageCommand extends ClientCommand {
+    private readonly known_preimages;
+    private queue;
+    readonly code = ClientCommandCode.GET_PREIMAGE;
+    constructor(known_preimages: ReadonlyMap<string, Buffer>, queue: Buffer[]);
+    execute(request: Buffer): Buffer;
+}
+export declare class GetMerkleLeafProofCommand extends ClientCommand {
+    private readonly known_trees;
+    private queue;
+    readonly code = ClientCommandCode.GET_MERKLE_LEAF_PROOF;
+    constructor(known_trees: ReadonlyMap<string, Merkle>, queue: Buffer[]);
+    execute(request: Buffer): Buffer;
+}
+export declare class GetMerkleLeafIndexCommand extends ClientCommand {
+    private readonly known_trees;
+    readonly code = ClientCommandCode.GET_MERKLE_LEAF_INDEX;
+    constructor(known_trees: ReadonlyMap<string, Merkle>);
+    execute(request: Buffer): Buffer;
+}
+export declare class GetMoreElementsCommand extends ClientCommand {
+    queue: Buffer[];
+    readonly code = ClientCommandCode.GET_MORE_ELEMENTS;
+    constructor(queue: Buffer[]);
+    execute(request: Buffer): Buffer;
+}
+/**
+ * This class will dispatch a client command coming from the hardware device to
+ * the appropriate client command implementation. Those client commands
+ * typically requests data from a merkle tree or merkelized maps.
+ *
+ * A ClientCommandInterpreter is prepared by adding the merkle trees and
+ * merkelized maps it should be able to serve to the hardware device. This class
+ * doesn't know anything about the semantics of the data it holds, it just
+ * serves merkle data. It doesn't even know in what context it is being
+ * executed, ie SignPsbt, getWalletAddress, etc.
+ *
+ * If the command yelds results to the client, as signPsbt does, the yielded
+ * data will be accessible after the command completed by calling getYielded(),
+ * which will return the yields in the same order as they came in.
+ */
+export declare class ClientCommandInterpreter {
+    private readonly roots;
+    private readonly preimages;
+    private yielded;
+    private queue;
+    private readonly commands;
+    constructor(progressCallback?: () => void);
+    getYielded(): readonly Buffer[];
+    addKnownPreimage(preimage: Buffer): void;
+    addKnownList(elements: readonly Buffer[]): void;
+    addKnownMapping(mm: MerkleMap): void;
+    addKnownWalletPolicy(wp: WalletPolicy): void;
+    execute(request: Buffer): Buffer;
+}
+export {};

package/types/ledger/bitcoin_client/lib/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const MAX_SCRIPT_BLOCK = 50;
+export declare const DEFAULT_VERSION = 1;
+export declare const DEFAULT_LOCKTIME = 0;
+export declare const DEFAULT_SEQUENCE = 4294967295;
+export declare const SIGHASH_ALL = 1;
+export declare const OP_DUP = 118;
+export declare const OP_HASH160 = 169;
+export declare const HASH_SIZE = 20;
+export declare const OP_EQUAL = 135;
+export declare const OP_EQUALVERIFY = 136;
+export declare const OP_CHECKSIG = 172;
+export declare const OP_RETURN = 106;

package/types/ledger/bitcoin_client/lib/merkelizedPsbt.d.ts

@@ -0,0 +1,24 @@
+import { MerkleMap } from './merkleMap';
+import { PsbtV2 } from './psbtv2';
+/**
+ * This class merkelizes a PSBTv2, by merkelizing the different
+ * maps of the psbt. This is used during the transaction signing process,
+ * where the hardware app can request specific parts of the psbt from the
+ * client code and be sure that the response data actually belong to the psbt.
+ * The reason for this is the limited amount of memory available to the app,
+ * so it can't always store the full psbt in memory.
+ *
+ * The signing process is documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md#sign_psbt
+ */
+export declare class MerkelizedPsbt extends PsbtV2 {
+    readonly globalMerkleMap: MerkleMap;
+    inputMerkleMaps: MerkleMap[];
+    outputMerkleMaps: MerkleMap[];
+    inputMapCommitments: Buffer[];
+    outputMapCommitments: Buffer[];
+    constructor(psbt: PsbtV2);
+    getGlobalSize(): number;
+    getGlobalKeysValuesRoot(): Buffer;
+    private static createMerkleMap;
+}

package/types/ledger/bitcoin_client/lib/merkle.d.ts

@@ -0,0 +1,32 @@
+/**
+ * This class implements the merkle tree used by Ledger Bitcoin app v2+,
+ * which is documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/merkle.md
+ */
+export declare class Merkle {
+    private leaves;
+    private rootNode;
+    private leafNodes;
+    private h;
+    constructor(leaves: Buffer[], hasher?: (buf: Buffer) => Buffer);
+    getRoot(): Buffer;
+    size(): number;
+    getLeaves(): Buffer[];
+    getLeafHash(index: number): Buffer;
+    getProof(index: number): Buffer[];
+    calculateRoot(leaves: Buffer[]): {
+        leaves: Node[];
+        root: Node;
+    };
+    hashNode(left: Buffer, right: Buffer): Buffer;
+}
+export declare function hashLeaf(buf: Buffer, hashFunction?: (buf: Buffer) => Buffer): Buffer;
+declare class Node {
+    leftChild?: Node;
+    rightChild?: Node;
+    parent?: Node;
+    hash: Buffer;
+    constructor(left: Node | undefined, right: Node | undefined, hash: Buffer);
+    isLeaf(): boolean;
+}
+export {};

package/types/ledger/bitcoin_client/lib/merkleMap.d.ts

@@ -0,0 +1,23 @@
+import { Merkle } from './merkle';
+/**
+ * This implements "Merkelized Maps", documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/merkle.md#merkleized-maps
+ *
+ * A merkelized map consist of two merkle trees, one for the keys of
+ * a map and one for the values of the same map, thus the two merkle
+ * trees have the same shape. The commitment is the number elements
+ * in the map followed by the keys' merkle root followed by the
+ * values' merkle root.
+ */
+export declare class MerkleMap {
+    readonly keys: readonly Buffer[];
+    readonly keysTree: Merkle;
+    readonly values: readonly Buffer[];
+    readonly valuesTree: Merkle;
+    /**
+     * @param keys Sorted list of (unhashed) keys
+     * @param values values, in corresponding order as the keys, and of equal length
+     */
+    constructor(keys: readonly Buffer[], values: readonly Buffer[]);
+    commitment(): Buffer;
+}

package/types/ledger/bitcoin_client/lib/policy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Bitcon hardware app uses a descriptors-like thing to describe
+ * how to construct output scripts from keys. A "Wallet Policy" consists
+ * of a "Descriptor Template" and a list of "keys". A key is basically
+ * a serialized BIP32 extended public key with some added derivation path
+ * information. This is documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/wallet.md
+ */
+export declare class WalletPolicy {
+    readonly name: string;
+    readonly descriptorTemplate: string;
+    readonly keys: readonly string[];
+    /**
+     * Creates and instance of a wallet policy.
+     * @param name an ascii string, up to 16 bytes long; it must be an empty string for default wallet policies
+     * @param descriptorTemplate the wallet policy template
+     * @param keys and array of the keys, with the key derivation information
+     */
+    constructor(name: string, descriptorTemplate: string, keys: readonly string[]);
+    /**
+     * Returns the unique 32-bytes id of this wallet policy.
+     */
+    getId(): Buffer;
+    /**
+     * Serializes the wallet policy for transmission via the hardware wallet protocol.
+     * @returns the serialized wallet policy
+     */
+    serialize(): Buffer;
+}
+export type DefaultDescriptorTemplate = 'pkh(@0/**)' | 'sh(wpkh(@0/**))' | 'wpkh(@0/**)' | 'tr(@0/**)';
+/**
+ * Simplified class to handle default wallet policies that can be used without policy registration.
+ */
+export declare class DefaultWalletPolicy extends WalletPolicy {
+    constructor(descriptorTemplate: DefaultDescriptorTemplate, key: string);
+}