Add TypeDoc to lisk-transactions (#7909)

### What was the problem? This PR resolves #7901 Please note there is currently a bug in TypeDoc with the effect that references between packages are not working, see TypeStrong/typedoc#1835 ### How was it solved? - Export relevant data structures - Add relevant code comments - Add typedoc to the dev dependencies - Add typedoc options to the `package.json` in each package. - Create typedoc.json and include required options for generating the docs properly. - Create new folder `docs/typedoc` to store generated typeDocs ### How was it tested? `cd lisk-sdk/` `npx typedoc` ### Result https://liskhq.github.io/lisk-docs/lisk-sdk/v6/references/typedoc/modules/_liskhq_lisk_transactions.html
LiskArchive · Jan 9, 2023 · fa63da6 · fa63da6
1 parent 3214cf7
commit fa63da6
Show file tree

Hide file tree

Showing 24 changed files with 358 additions and 10 deletions.
diff --git a/commander/README.md b/commander/README.md
@@ -16,7 +16,7 @@ Upon successful completion, NPM will add the `lisk-commander` executable `lisk`
 
 ## Usage
 
-```sh-session
+```shell
 $ lisk COMMAND
 running command...
 $ lisk (-v|--version|version)

diff --git a/commander/package.json b/commander/package.json
@@ -23,6 +23,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist/index.js",
 	"bin": {
 		"lisk": "./bin/run"

diff --git a/elements/lisk-api-client/package.json b/elements/lisk-api-client/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-chain/package.json b/elements/lisk-chain/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-codec/package.json b/elements/lisk-codec/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-cryptography/package.json b/elements/lisk-cryptography/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-p2p/package.json b/elements/lisk-p2p/package.json
@@ -21,6 +21,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-passphrase/package.json b/elements/lisk-passphrase/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-transaction-pool/package.json b/elements/lisk-transaction-pool/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"typings": "dist-node/index.d.ts",
 	"scripts": {

diff --git a/elements/lisk-transactions/package.json b/elements/lisk-transactions/package.json
@@ -20,6 +20,11 @@
 		"node": ">=16.14.1 <=16",
 		"npm": ">=8.1.0"
 	},
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"tsconfig": "./tsconfig.json"
+	},
 	"main": "dist-node/index.js",
 	"scripts": {
 		"clean": "./scripts/clean.sh",

diff --git a/elements/lisk-transactions/src/constants.ts b/elements/lisk-transactions/src/constants.ts
@@ -14,4 +14,13 @@
 
 import { utils } from '@liskhq/lisk-cryptography';
 
+/**
+ * The transaction tag is used during the signature creation to create unique signatures for transactions.
+ *
+ * The tag for transactions is `LSK_TX` as defined in the Lisk protocol.
+ * For more information, check out the corresponding LIPs.
+ *
+ * @see [LIP 0037 - Use message tags and chain identifiers for signatures](https://github.com/LiskHQ/lips/blob/main/proposals/lip-0037.md) and
+ * @see [LIP 0068 - Define new transaction schema](https://github.com/LiskHQ/lips/blob/main/proposals/lip-0068.md) for more information about message tags.
+ */
 export const TAG_TRANSACTION = utils.createMessageTag('TX');
diff --git a/elements/lisk-transactions/src/fee.ts b/elements/lisk-transactions/src/fee.ts
@@ -15,16 +15,42 @@
 
 import { getBytes } from './sign';
 
+/** Available options for {@link computeMinFee} */
 export interface Options {
+	/** Minimum fee per byte. Default value: {@link DEFAULT_MIN_FEE_PER_BYTE} */
 	readonly minFeePerByte?: number;
+	/** Number of signatures included in the transaction. Default value: {@link DEFAULT_NUMBER_OF_SIGNATURES} */
 	readonly numberOfSignatures?: number;
+	/** Number of empty signatures in the transaction. Default value: {@link DEFAULT_SIGNATURE_BYTE_SIZE} */
 	readonly numberOfEmptySignatures?: number;
 }
 
-const DEFAULT_MIN_FEE_PER_BYTE = 1000;
-const DEFAULT_NUMBER_OF_SIGNATURES = 1;
-const DEFAULT_SIGNATURE_BYTE_SIZE = 64;
+/** Default value for `minFeePerByte`. */
+export const DEFAULT_MIN_FEE_PER_BYTE = 1000;
+/** Default value for `numberOfSignatures`. */
+export const DEFAULT_NUMBER_OF_SIGNATURES = 1;
+/** Default byte size for transaction signatures. */
+export const DEFAULT_SIGNATURE_BYTE_SIZE = 64;
 
+/**
+ * Computes the minimum fee for a provided transaction.
+ *
+ *  @example
+ *  ```ts
+ *  import { computeMinFee } from '@liskhq/lisk-transactions';
+ *  const minFee = computeMinFee(TransferTrx, transferParamsSchema, options);
+ *  ```
+ *
+ * @param trx the {@link baseTransactionSchema | transaction}  object
+ * @param assetSchema Schema for the command parameters.
+ * The specific schemas for parameters are described in the [Modules reference](https://lisk.com/documentation/lisk-sdk/modules/index.html).
+ * @param options
+ *
+ * @returns Minimum fee for the provided transaction.
+ *
+ * @see [LIP 0013 - Replace static fee system by dynamic fee system](https://github.com/LiskHQ/lips/blob/main/proposals/lip-0013.md)
+ * @see [LIP 0048 - Introduce Fee Module](https://github.com/LiskHQ/lips/blob/main/proposals/lip-0048.md#minimum-fee-per-transaction)
+ * */
 export const computeMinFee = (
 	trx: Record<string, unknown>,
 	assetSchema?: object,

diff --git a/elements/lisk-transactions/src/format.ts b/elements/lisk-transactions/src/format.ts
@@ -20,6 +20,21 @@ const getDecimalPlaces = (amount: string): number =>
 	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 	(amount.split('.')[1] || '').length;
 
+/**
+ * Converts a given amount of Beddows to LSK.
+ * 1 LSK = 10^8 Beddows.
+ *
+ *  @example
+ *  ```ts
+ *  import { convertBeddowsToLSK } from '@liskhq/lisk-transactions';
+ *  const lskAmount = convertBeddowsToLSK("150000000");
+ *  ```
+ *
+ * @param beddowsAmount Amount in Beddows
+ *
+ * @returns Amount in LSK
+ *
+ * */
 export const convertBeddowsToLSK = (beddowsAmount?: string): string => {
 	if (typeof beddowsAmount !== 'string') {
 		throw new Error('Cannot convert non-string amount');
@@ -43,6 +58,20 @@ export const convertBeddowsToLSK = (beddowsAmount?: string): string => {
 	return res;
 };
 
+/**
+ * Converts a given amount of Beddows to LSK.
+ * 1 LSK = 10^8 Beddows.
+ *
+ *  @example
+ *  ```ts
+ *  import { convertLSKToBeddows } from '@liskhq/lisk-transactions';
+ *  const lskAmount = convertLSKToBeddows("15");
+ *  ```
+ *
+ * @param lskAmount Amount in LSK
+ *
+ * @returns Amount in Beddows
+ * */
 export const convertLSKToBeddows = (lskAmount?: string): string => {
 	if (typeof lskAmount !== 'string') {
 		throw new Error('Cannot convert non-string amount');

diff --git a/elements/lisk-transactions/src/index.ts b/elements/lisk-transactions/src/index.ts
@@ -13,9 +13,16 @@
  *
  */
 
-export { computeMinFee, Options } from './fee';
+export {
+	Options,
+	computeMinFee,
+	DEFAULT_MIN_FEE_PER_BYTE,
+	DEFAULT_NUMBER_OF_SIGNATURES,
+	DEFAULT_SIGNATURE_BYTE_SIZE,
+} from './fee';
 export { convertBeddowsToLSK, convertLSKToBeddows } from './format';
 export {
+	MultiSignatureKeys,
 	getBytes,
 	getSigningBytes,
 	signTransaction,
@@ -25,3 +32,4 @@ export {
 } from './sign';
 export { validateTransaction } from './validate';
 export * from './constants';
+export { baseTransactionSchema } from './schema';
diff --git a/elements/lisk-transactions/src/schema.ts b/elements/lisk-transactions/src/schema.ts
@@ -12,6 +12,12 @@
  * Removal or modification of this copyright notice is prohibited.
  *
  */
+
+/**
+ * Schema for Lisk Transactions.
+ *
+ * @see [LIP 0068 - Define new transaction schema](https://github.com/LiskHQ/lips/blob/main/proposals/lip-0068.md)
+ */
 export const baseTransactionSchema = {
 	$id: '/lisk/baseTransaction',
 	type: 'object',