@midnightntwrk/wallet-sdk-hd 3.0.3

package/README.md

@@ -0,0 +1,51 @@
+# Midnight SDK HD Wallet
+
+This package provides support for Hierarchical Deterministic (HD) Wallet.
+
+To allow deterministic derivation of keys for different features, Midnight follows algorithms and structure being a mix
+of [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki),
+[BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and
+[CIP-1852](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/README.md). Specifically, derivation follows
+BIP-32, and following path for a key pair is used:
+
+```
+m / purpose' / coin_type' / account' / role / index
+```
+
+Where:
+
+- `purpose` is integer `44` (`0x8000002c`) - despite extensions, Night part of the hierarchy follows BIP-44
+- `coin_type` is integer `2400` (`0x80000960`)
+- `account` follows BIP-44 recommendations
+- `role` follows table below
+- `index` follows BIP-44 recommendations
+
+| Role name            | Value | Description                                             |
+| -------------------- | ----- | ------------------------------------------------------- |
+| Night External chain | 0     | Night is Midnight's main token of value, Follows BIP-44 |
+| Night Internal chain | 1     | as above                                                |
+| Dust                 | 2     | Dust is needed to pay fees on Midnight                  |
+| Zswap                | 3     | Zswap is a sub-protocol for shielded native tokens      |
+| Metadata             | 4     | Keys for signing metadata                               |
+
+## How to derive the keys?
+
+Below you can find an example on how to derive keys from a random seed:
+
+```typescript
+import { generateRandomSeed, HDWallet, Roles } from '@midnightntwrk/wallet-sdk-hd';
+
+const seed = generateRandomSeed();
+const generatedWallet = HDWallet.fromSeed(seed);
+
+if (generatedWallet.type == 'seedOk') {
+  const zswapKey = generatedWallet.hdWallet.selectAccount(0).selectRole(Roles.Zswap).deriveKeyAt(0);
+  if (zswapKey.type === 'keyDerived') {
+    console.log('success', zswapKey.key);
+  } else {
+    console.error('Error deriving key');
+  }
+} else {
+  console.error('Error generating HDWallet');
+}
+```

package/dist/HDWallet.d.ts

@@ -0,0 +1,69 @@
+import { HDKey } from '@scure/bip32';
+type ValueOf<T> = T[keyof T];
+export declare const Roles: {
+    readonly NightExternal: 0;
+    readonly NightInternal: 1;
+    readonly Dust: 2;
+    readonly Zswap: 3;
+    readonly Metadata: 4;
+};
+export type Role = ValueOf<typeof Roles>;
+type DerivationResult = {
+    readonly type: 'keyDerived';
+    readonly key: Uint8Array;
+} | {
+    readonly type: 'keyOutOfBounds';
+};
+type CompositeDerivationResult<T extends readonly Role[]> = {
+    readonly type: 'keysDerived';
+    readonly keys: Record<T[number], Uint8Array>;
+} | {
+    readonly type: 'keyOutOfBounds';
+    readonly roles: readonly Role[];
+};
+type HDWalletResult = {
+    readonly type: 'seedOk';
+    readonly hdWallet: HDWallet;
+} | {
+    readonly type: 'seedError';
+    readonly error: unknown;
+};
+declare const CompositeDerivationResult: {
+    fromResults: <T extends readonly Role[]>(results: {
+        role: T[number];
+        result: DerivationResult;
+    }[]) => CompositeDerivationResult<T>;
+};
+export declare class HDWallet {
+    private readonly rootKey;
+    private constructor();
+    static fromSeed(seed: Uint8Array): HDWalletResult;
+    selectAccount(account: number): AccountKey;
+    /**
+     * Once all keys are derived - clear internals from private data, so that they do not reside in memory longer than
+     * needed.
+     */
+    clear(): void;
+}
+export declare class AccountKey {
+    private readonly rootKey;
+    private readonly account;
+    constructor(rootKey: HDKey, account: number);
+    selectRole(role: Role): RoleKey;
+    selectRoles<T extends readonly Role[]>(roles: T): CompositeRoleKey<T>;
+}
+export declare class RoleKey {
+    private readonly rootKey;
+    private readonly account;
+    private readonly role;
+    constructor(rootKey: HDKey, account: number, role: Role);
+    deriveKeyAt(index: number): DerivationResult;
+}
+export declare class CompositeRoleKey<T extends readonly Role[]> {
+    private readonly rootKey;
+    private readonly account;
+    private readonly roles;
+    constructor(rootKey: HDKey, account: number, roles: T);
+    deriveKeysAt(index: number): CompositeDerivationResult<T>;
+}
+export {};

package/dist/HDWallet.js

@@ -0,0 +1,121 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { HARDENED_OFFSET, HDKey } from '@scure/bip32';
+export const Roles = {
+    NightExternal: 0,
+    NightInternal: 1,
+    Dust: 2,
+    Zswap: 3,
+    Metadata: 4,
+};
+const PURPOSE = 44;
+const COIN_TYPE = 2400;
+// BIP32 path components (account, role, index) are integers in [0, 2^31);
+// @scure/bip32 inlines this check inside derive() and throws, so guard here
+const isValidChildIndex = (value) => Number.isSafeInteger(value) && value >= 0 && value < HARDENED_OFFSET;
+const CompositeDerivationResult = {
+    fromResults: (results) => {
+        const { succeededKeys, failedRoles } = results.reduce((acc, result) => {
+            if (result.result.type === 'keyDerived') {
+                acc.succeededKeys[result.role] = result.result.key;
+            }
+            else {
+                acc.failedRoles.push(result.role);
+            }
+            return acc;
+        }, { succeededKeys: {}, failedRoles: [] });
+        if (failedRoles.length > 0) {
+            return { type: 'keyOutOfBounds', roles: failedRoles };
+        }
+        else {
+            return { type: 'keysDerived', keys: succeededKeys };
+        }
+    },
+};
+export class HDWallet {
+    rootKey;
+    constructor(key) {
+        this.rootKey = key;
+    }
+    static fromSeed(seed) {
+        try {
+            const rootKey = HDKey.fromMasterSeed(seed);
+            return { type: 'seedOk', hdWallet: new HDWallet(rootKey) };
+        }
+        catch (e) {
+            return { type: 'seedError', error: e };
+        }
+    }
+    // Begin by selecting an account.
+    selectAccount(account) {
+        return new AccountKey(this.rootKey, account);
+    }
+    /**
+     * Once all keys are derived - clear internals from private data, so that they do not reside in memory longer than
+     * needed.
+     */
+    clear() {
+        this.rootKey.wipePrivateData();
+    }
+}
+export class AccountKey {
+    rootKey;
+    account;
+    constructor(rootKey, account) {
+        this.account = account;
+        this.rootKey = rootKey;
+    }
+    // After account, select a role.
+    selectRole(role) {
+        return new RoleKey(this.rootKey, this.account, role);
+    }
+    selectRoles(roles) {
+        return new CompositeRoleKey(this.rootKey, this.account, roles);
+    }
+}
+export class RoleKey {
+    rootKey;
+    account;
+    role;
+    constructor(rootKey, account, role) {
+        this.role = role;
+        this.account = account;
+        this.rootKey = rootKey;
+    }
+    // Finally, derive the key at the given index.
+    deriveKeyAt(index) {
+        if (![this.account, this.role, index].every(isValidChildIndex)) {
+            return { type: 'keyOutOfBounds' };
+        }
+        const path = `m/${PURPOSE}'/${COIN_TYPE}'/${this.account}'/${this.role}/${index}`;
+        const derivedKey = this.rootKey.derive(path);
+        return derivedKey.privateKey ? { type: 'keyDerived', key: derivedKey.privateKey } : { type: 'keyOutOfBounds' };
+    }
+}
+export class CompositeRoleKey {
+    rootKey;
+    account;
+    roles;
+    constructor(rootKey, account, roles) {
+        this.roles = roles;
+        this.rootKey = rootKey;
+        this.account = account;
+    }
+    deriveKeysAt(index) {
+        const results = this.roles.map((role) => ({
+            role,
+            result: new RoleKey(this.rootKey, this.account, role).deriveKeyAt(index),
+        }));
+        return CompositeDerivationResult.fromResults(results);
+    }
+}

package/dist/MnemonicUtils.d.ts

@@ -0,0 +1,7 @@
+export declare const mnemonicToWords: (mnemonic: string) => string[];
+/** A wrapper around the bip39 package function, with default strength applied to produce 24 words */
+export declare const generateMnemonicWords: (strength?: number) => string[];
+export declare const joinMnemonicWords: (mnenomic: string[]) => string;
+export declare const generateRandomSeed: (strength?: number) => Uint8Array;
+/** A wrapper around the bip39 package function */
+export declare const validateMnemonic: (mnemonic: string) => boolean;

package/dist/MnemonicUtils.js

@@ -0,0 +1,23 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as bip39 from '@scure/bip39';
+import { wordlist as english } from '@scure/bip39/wordlists/english.js';
+export const mnemonicToWords = (mnemonic) => mnemonic.split(' ');
+/** A wrapper around the bip39 package function, with default strength applied to produce 24 words */
+export const generateMnemonicWords = (strength = 256) => mnemonicToWords(bip39.generateMnemonic(english, strength));
+export const joinMnemonicWords = (mnenomic) => mnenomic.join(' ');
+export const generateRandomSeed = (strength = 256) => {
+    return crypto.getRandomValues(new Uint8Array(Math.ceil(strength / 8)));
+};
+/** A wrapper around the bip39 package function */
+export const validateMnemonic = (mnemonic) => bip39.validateMnemonic(mnemonic, english);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './HDWallet.js';
+export * from './MnemonicUtils.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export * from './HDWallet.js';
+export * from './MnemonicUtils.js';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@midnightntwrk/wallet-sdk-hd",
+  "version": "3.0.3",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnightntwrk/midnight-wallet.git",
+    "directory": "packages/hd"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@scure/bip32": "^2.0.1",
+    "@scure/bip39": "^2.0.1"
+  },
+  "devDependencies": {
+    "@ethereumjs/wallet": "10.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit --force",
+    "test": "vitest run",
+    "lint": "eslint --max-warnings 0",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "dist": "tsc -b ./tsconfig.build.json",
+    "dist:publish": "tsc -b ./tsconfig.publish.json",
+    "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo' && date +%s > .clean-timestamp",
+    "publint": "publint --strict"
+  }
+}