feat: add xrpl-secret-numbers to the monorepo (#2445)

- Add `xrpl-secret-numbers` by @WietseWind to the mono repo. - `unpkg` and `jsdelivr` support was simplified by adding fields to package.json. - Unit tests run in a browser and node. BREAKING CHANGES: - `xrpl-secret-numbers` is now `@xrplf/secret-numbers`. - Changed the bundled file produced changed from `dist/browerified.js` to `build/xrplf-secret-numbers-latest.js`. - Bundle variable is `xrplf_secret_numbers` instead of using browserify's loader. - If using CDN instructions in README will need to update to `https://cdn.jsdelivr.net/npm/@xrplf/secret-numbers` Making this library part of the monorepo was discussed in #1788. This solves several problems with the upcoming `xrpl.js@3.0`. `xrpl-secret-numbers` has a dependency of `ripple-keypairs` and `xrpl` has a depenendecy on `xrpl-secret-numbers`. This means that any change would require a separate release of `ripple-keypairs`, then a release of `xrpl-secret-numbers`, followed by `xrpl`. Now they can be released all at once In 3.0 we eliminated the need for many polyfills like `util`, `assert`, and soon to be `buffer` (after noble libs PR is merged). `xrpl-secret-numbers` still needs those. This will also eliminate them and anytime similar changes in the future will be much easier. This further reduces the bundle size of 3.0 branch by over 10% as well as reducing bundler setup.
XRPLF · Oct 25, 2023 · 091cc8f · 091cc8f
1 parent fff1c96
commit 091cc8f
Show file tree

Hide file tree

Showing 30 changed files with 1,007 additions and 174 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -14,6 +14,7 @@
     "update:confirm": "npx npm-check-updates --configFileName .ncurc.json -u"
   },
   "dependencies": {
+    "@xrplf/ripple-keypairs": "file:packages/secret-numbers",
     "ripple-address-codec": "file:packages/ripple-address-codec",
     "ripple-binary-codec": "file:packages/ripple-binary-codec",
     "ripple-keypairs": "file:packages/ripple-keypairs",

diff --git a/packages/secret-numbers/.eslintignore b/packages/secret-numbers/.eslintignore
@@ -0,0 +1,12 @@
+# Don't ever lint node_modules
+node_modules
+
+# Don't lint build output
+dist
+
+# don't lint nyc coverage output
+coverage
+.nyc_output
+
+# Don't lint NYC configuration
+nyc.config.js
diff --git a/packages/secret-numbers/.eslintrc.js b/packages/secret-numbers/.eslintrc.js
@@ -0,0 +1,47 @@
+module.exports = {
+  root: true,
+
+  parser: "@typescript-eslint/parser", // Make ESLint compatible with TypeScript
+  parserOptions: {
+    // Enable linting rules with type information from our tsconfig
+    tsconfigRootDir: __dirname,
+    project: ["./tsconfig.eslint.json"],
+
+    sourceType: "module", // Allow the use of imports / ES modules
+
+    ecmaFeatures: {
+      impliedStrict: true, // Enable global strict mode
+    },
+  },
+
+  // Specify global variables that are predefined
+  env: {
+    browser: true, // Enable browser global variables
+    node: true, // Enable node global variables & Node.js scoping
+    es2020: true, // Add all ECMAScript 2020 globals and automatically set the ecmaVersion parser option to ES2020
+  },
+
+  plugins: [],
+  extends: ["@xrplf/eslint-config/base"],
+
+  rules: {
+    // This creates a lot of false positives. We should turn this off in our
+    // general config.
+    "jsdoc/require-description-complete-sentence": "off",
+
+    // ** TODO **
+    // all of the below are turned off for now during the migration to a
+    // monorepo. They need to actually be addressed!
+    // **
+    "@typescript-eslint/no-magic-numbers": "off",
+    "jsdoc/require-returns": "off",
+    "jsdoc/check-param-names": "off",
+    "jsdoc/require-throws": "off",
+    "jsdoc/require-jsdoc": "off",
+    "jsdoc/require-param": "off",
+    "jsdoc/check-examples": "off", // Not implemented in eslint 8
+    "tsdoc/syntax": "off",
+    "@typescript-eslint/no-require-imports": "off",
+    "@typescript-eslint/explicit-member-accessibility": "off",
+  },
+};
diff --git a/packages/secret-numbers/HISTORY.md b/packages/secret-numbers/HISTORY.md
@@ -0,0 +1,14 @@
+# @xrplf/secret-numbers (xrpl-secret-numbers) Release History
+
+Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xrpl-announce) for release announcements. We recommend that `@xrplf/secret-numbers` users stay up-to-date with the latest stable release.
+
+## Unreleased
+
+- Add `xrpl-secret-numbers` by @WietseWind  to the mono repo.
+- `unpkg` and `jsdelivr` support was simplified.
+- Unit tests run in a browser and node.
+
+### BREAKING CHANGES:
+- `xrpl-secret-numbers` is now `@xrplf/secret-numbers`.
+- The bundled file produced changed from  `dist/browerified.js` to `build/xrplf-secret-numbers-latest.js`.
+- Bundle variable is `xrplf_secret_numbers` instead of using browserify's loader.
diff --git a/packages/secret-numbers/LICENSE b/packages/secret-numbers/LICENSE
@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2019-2023 Contributers to xrpl.js
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
diff --git a/packages/secret-numbers/README.md b/packages/secret-numbers/README.md
@@ -0,0 +1,97 @@
+# XRPL Secret Numbers [![npm version](https://badge.fury.io/js/@xrplf%2Fsecret-numbers.svg)](https://www.npmjs.com/@xrplf/secret-numbers)
+
+For more background information, please read the [proposed Standard](https://github.com/xrp-community/standards-drafts/issues/15).
+
+A tool to convert Secret Numbers to the widely used Family Seed `s...` format is [available here](https://github.com/WietseWind/secret-numbers-to-family-seed/releases)
+
+A bundled version of this lib is available at NPM (`build/xrplf-secret-numbers-latest.js`), CDN: https://cdn.jsdelivr.net/npm/@xrplf/secret-numbers. You can access the library as `xrplf_secret_numbers`. Sample:
+https://jsfiddle.net/WietseWind/uo1zy0q7/
+
+#### Generate XRPL Accounts with a number-based secret: 8 chunks of 6 digits.
+
+The common formats for XRPL account secrets are (at the time of writing this, July 2019):
+
+- Family Seed, eg. `sh1HiK7SwjS1VxFdXi7qeMHRedrYX`
+- Mnemonic, eg. `car banana apple road ...`
+
+These formats are prone to typo's and not that user friendly. Using numbers means it's language (spoken, written) agnostic as well. They may be especially intimidating for the public that's relatively new to cryptocurrencies / blockchain technology.
+
+This library encodes the entropy to generate accounts into 8 chunks of 6 digits, of which 5 digits are 1/8th of the entropy, and a 6th digit contains a checksum allowing realtime typo detection.
+
+##### A secret now looks like:
+
+```
+554872 394230 209376 323698
+140250 387423 652803 258676
+```
+
+For compatibility with existing clients, this library supports exporting the family seed for a generated / entered "Secret Number"-set as well.
+
+## API
+
+The typescript code to use resides in `./src/` and the compiled js in `./dist/` of the package. See the `./samples/` folder for some simple JS samples.
+
+##### Generating a new account:
+
+```
+const {Account} = require('@xrplf/secret-numbers')
+const account = new Account()
+```
+
+##### Importing an existing account:
+
+```
+const {Account} = require('@xrplf/secret-numbers')
+const secret = '399150 474506 009147 088773 432160 282843 253738 605430'
+const account = new Account(secret)
+```
+
+Or importing with custom entropy (buffer, 16):
+
+```
+const {Account} = require('@xrplf/secret-numbers')
+const entropy = Buffer.from('0123456789ABCDEF0123456789ABCDEF', 'hex')
+const account = new Account(entropy)
+```
+
+##### After generating / importing:
+
+You can fetch the account details (address, secret, etc.) using these methods:
+
+```
+console.log(account.getAddress())
+console.log(account.getSecret())
+```
+
+##### Available methods:
+
+- `getSecret()`: Array<string>[8]
+- `getSecretString()`: string `012345 456789 ...`
+- `getAddress()`: string `rXXXXXXXX...`
+- `getFamilySeed()`: string `sXXXXXXXX...`
+- `getKeypair()`: `Keypair({privateKey, publicKey}`
+
+##### To split/check/encode/decode some more:
+
+There's a `Utils` export as well:
+
+```
+const {Account, Utils} = require('@xrplf/secret-numbers')
+```
+
+Some Utils methods (that you may want to use in your UI / ... before using the Account constructor):
+
+ - To calculate the 6th decimal for a group of 5 digits:  
+   `calculateChecksum(position: number, value: number)`: number
+ - To check a checksum (either sliced or the 6th char of a string containing numbers:  
+   `checkChecksum(position: number, value: number | string, checksum?: number)`: Boolean
+
+## Development
+
+Run `npm run prepublish` to clean, lint, test and build. Or just run `npm run build`, `npm run test` or `npm run lint`. 
+
+Tests are in `./test/`
+
+## Credits
+
+This concept is based on an idea by [@nbougalis](https://github.com/nbougalis).
diff --git a/packages/secret-numbers/jest.config.js b/packages/secret-numbers/jest.config.js
@@ -0,0 +1,8 @@
+// Jest configuration for api
+const base = require("../../jest.config.base.js");
+
+module.exports = {
+  ...base,
+  roots: [...base.roots, "<rootDir>/test"],
+  displayName: "@xrplf/secret-numbers",
+};
diff --git a/packages/secret-numbers/karma.config.js b/packages/secret-numbers/karma.config.js
@@ -0,0 +1,39 @@
+const webpackConfig = require("./test/webpack.config");
+delete webpackConfig.entry;
+
+module.exports = function (config) {
+  config.set({
+    plugins: ["karma-webpack", "karma-jasmine", "karma-chrome-launcher"],
+
+    // base path that will be used to resolve all patterns (eg. files, exclude)
+    basePath: "",
+
+    webpack: webpackConfig,
+
+    // frameworks to use
+    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
+    frameworks: ["jasmine"],
+
+    // list of files / patterns to load in the browser
+    files: ["build/xrplf-secret-numbers-latest.js", "test/*.test.ts"],
+
+    // preprocess matching files before serving them to the browser
+    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
+    preprocessors: {
+      // Use webpack to bundle our test files
+      "test/*.test.ts": ["webpack"],
+    },
+
+    browsers: ["ChromeHeadless"],
+    // runs only one browser at a time
+    concurrency: 1,
+    // CI mode
+    singleRun: true,
+    client: {
+      jasmine: {
+        // ensures that tests are run in order instead of a random order
+        random: false,
+      },
+    },
+  });
+};