README checks (#2841)

.github/workflows/test.yml

@@ -37,3 +37,5 @@ jobs:
         run: yarn coverage
       - name: E2e tests
         run: yarn test:e2e
+      - name: README check
+        run: yarn run check-readme

package.json

@@ -29,7 +29,8 @@
     "cli": "node --trace-deprecation --max-old-space-size=8192 ./packages/cli/bin/lodestar",
     "publish:release": "lerna publish from-package --yes --no-verify-access",
     "release": "lerna version --no-push --sign-git-commit",
-    "postrelease": "git tag -d $(git describe --abbrev=0)"
+    "postrelease": "git tag -d $(git describe --abbrev=0)",
+    "check-readme": "lerna run check-readme"
   },
   "devDependencies": {
     "@babel/cli": "^7.12.8",
@@ -72,7 +73,7 @@
     "typedoc-plugin-internal-external": "^2.2.0",
     "typedoc-plugin-markdown": "^2.4.1",
     "typescript": "^4.2.0",
-    "webpack": "^5.36.2"
+    "typescript-docs-verifier": "^1.1.3"
   },
   "dependencies": {},
   "resolutions": {

packages/api/README.md

@@ -13,18 +13,16 @@ Typescript REST client for the [Eth2.0 API spec](https://ethereum.github.io/eth2
 
 ```typescript
 import {getClient} from "@chainsafe/lodestar-api";
-import {config} from "@chainsafe/lodestar-config/mainnet";
+import {config} from "@chainsafe/lodestar-config/default";
 
 const api = getClient(config, {
   baseUrl: "http://localhost:9596",
 });
 
-const res = await api.state.getStateValidator(
+api.beacon.getStateValidator(
   "head",
   "0x933ad9491b62059dd065b560d256d8957a8c402cc6e8d8ee7290ae11e8f7329267a8811c397529dac52ae1342ba58c95"
-);
-
-console.log("Your balance is:", res.data.balance);
+).then((res) => console.log("Your balance is:", res.data.balance));
 ```
 
 ## Prerequisites

packages/api/package.json

@@ -33,7 +33,8 @@
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
     "test": "yarn test:unit && yarn test:e2e",
-    "test:unit": "nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'"
+    "test:unit": "nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "dependencies": {
     "@chainsafe/abort-controller": "^3.0.1",

packages/beacon-state-transition/README.md

@@ -14,24 +14,24 @@ The beacon state transition and state transition utilities
 
 ```typescript
 
-import {stateTransition} from "@chainsafe/lodestar-beacon-state-transition";
-import {BeaconBlock, BeaconState} from "@chainsafe/lodestar-types";
-import {mainnetConfig} from "@chainsafe/lodestar-config/mainnet";
+import {CachedBeaconState, stateTransition} from "@chainsafe/lodestar-beacon-state-transition/src/allForks";
+import {allForks} from "@chainsafe/lodestar-types";
+import {generateEmptySignedBlock} from "../test/utils/block";
+import {generateState} from "../test/utils/state";
 
-const state: BeaconState = {
-  ...
-};
+// dummy test state
+const state: CachedBeaconState<allForks.BeaconState> = generateState() as CachedBeaconState<allForks.BeaconState>;
 
-const block: BeaconBlock = {
-  ...
-};
+// dummy test block 
+const block: allForks.SignedBeaconBlock = generateEmptySignedBlock();
 
-let postStateContext: BeaconState;
+let postStateContext: allForks.BeaconState;
 try {
-  postStateContext = stateTransition(mainnetConfig, state, block);
+  postStateContext = stateTransition(state, block);
 } catch (e) {
   console.log(e);
 }
+
 ```
 
 ## License

packages/beacon-state-transition/package.json

@@ -32,7 +32,8 @@
     "check-types": "tsc",
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
-    "test:unit": "mocha 'test/unit/**/*.test.ts'"
+    "test:unit": "mocha 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "types": "lib/index.d.ts",
   "dependencies": {

packages/cli/package.json

@@ -36,7 +36,8 @@
     "test:unit": "nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'",
     "test:e2e": "mocha --timeout 30000 'test/e2e/**/*.test.ts'",
     "test": "yarn test:unit && yarn test:e2e",
-    "coverage": "codecov -F lodestar"
+    "coverage": "codecov -F lodestar",
+    "check-readme": "typescript-docs-verifier"
   },
   "repository": {
     "type": "git",

packages/config/README.md

@@ -31,31 +31,54 @@ The Lodestar config package contains several interfaces used in downstream Lodes
 
 The Ethereum consensus spec defines a bunch of variables that may be easily configured per testnet. These include the `GENESIS_TIME`, `SECONDS_PER_SLOT`, and various `*_FORK_EPOCH`s, `*_FORK_VERSION`s, etc. The Lodestar config package exports the `IChainConfig` interface and matching `ChainConfig` SSZ type, which include all of these variables, named verbatim from the spec.
 
-```ts
+```typescript
 import {IChainConfig} from "@chainsafe/lodestar-config";
+import {chainConfig} from "@chainsafe/lodestar-config/default";
 
-let chainConfig: IChainConfig;
-const x: number = chainConfig.SECONDS_PER_SLOT;
+let config: IChainConfig = chainConfig;
+const x: number = config.SECONDS_PER_SLOT;
 ```
 
 Mainnet default values are available as a singleton `IChainConfig` under the `default` import path.
 
-```ts
+```typescript
 import {chainConfig} from "@chainsafe/lodestar-config/default";
 
 chainConfig.SECONDS_PER_SLOT === 12;
 ```
 
 There are also utility functions to help create a `IChainConfig` from unknown input and partial configs.
 
-```ts
+```typescript
 import {createIChainConfig, IChainConfig, parsePartialIChainConfigJson} from "@chainsafe/lodestar-config";
 
-const chainConfigObj: Record<string, unknown> = {
-  // Eg: read yaml file into an object
-};
-
-const partialChainConfig: Partial<IChainConfig> = parsePartialIChainConfigJson(configObj);
+// example config
+let chainConfigObj: Record<string, unknown> = {
+  // phase0
+  MIN_PER_EPOCH_CHURN_LIMIT: 4,
+  CHURN_LIMIT_QUOTIENT: 65536,
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 128,
+  MIN_GENESIS_TIME: 1621504614,
+  ETH1_FOLLOW_DISTANCE: 2048,
+  SECONDS_PER_ETH1_BLOCK: 14,
+  DEPOSIT_CHAIN_ID: 5,
+  DEPOSIT_NETWORK_ID: 5,
+  DEPOSIT_CONTRACT_ADDRESS: "0x2cc88381fe23027743c1f85512bffb383acca7c7",
+  EJECTION_BALANCE: 16000000000,
+  GENESIS_FORK_VERSION: "0x00004811",
+  GENESIS_DELAY: 1100642,
+  SECONDS_PER_SLOT: 12,
+  MIN_VALIDATOR_WITHDRAWABILITY_DELAY: 256,
+  SHARD_COMMITTEE_PERIOD: 256,
+
+  // altair
+  INACTIVITY_SCORE_BIAS: 4,
+  INACTIVITY_SCORE_RECOVERY_RATE: 16,
+  ALTAIR_FORK_VERSION: "0x01004811",
+  ALTAIR_FORK_EPOCH: 10,
+}
+
+const partialChainConfig: Partial<IChainConfig> = parsePartialIChainConfigJson(chainConfigObj);
 
 // Fill in the missing values with mainnet default values
 const chainConfig: IChainConfig = createIChainConfig(partialChainConfig);
@@ -67,11 +90,10 @@ The variables described in the spec can be used to assemble a more structured 'f
 
 A `IForkConfig` provides methods to select the fork info, fork name, fork version, or fork ssz types given a slot. 
 
-```ts
+```typescript
 import {GENESIS_SLOT} from "@chainsafe/lodestar-params";
-import {createIChainForkConfig, IChainConfig, IChainForkConfig} from "@chainsafe/lodestar-config";
-
-let chainConfig: IChainConfig;
+import {createIChainForkConfig, IChainForkConfig} from "@chainsafe/lodestar-config";
+import {config as chainConfig} from "@chainsafe/lodestar-config/default";
 
 const config: IChainForkConfig = createIChainForkConfig(chainConfig);
 
@@ -82,12 +104,13 @@ const version = config.getForkVersion(GENESIS_SLOT);
 
 For signing Ethereum consensus objects, a cryptographic "domain" is computed and mixed into the signed message. This domain separates signatures made for the Ethereum mainnet from testnets or other instances of the chain. The `ICachedGenesis` interface is used to provide a cache for this purpose. Practically, the domain rarely changes, only per-fork, and so the value can be easily cached. Since the genesis validators root is part of the domain, it is required input to instantiate an `ICachedGenesis`. In practice, the `IChainForkConfig` and `ICachedGenesis` are usually combined as a `IBeaconConfig`. This is the 'highest level' object exported by the Lodestar config library.
 
-```ts
+```typescript
 import {DOMAIN_DEPOSIT, GENESIS_SLOT} from "@chainsafe/lodestar-params";
-import {createIBeaconConfig, IBeaconConfig, IChainConfig} from "@chainsafe/lodestar-config";
+import {createIBeaconConfig, IBeaconConfig} from "@chainsafe/lodestar-config";
+import {config as chainConfig} from "@chainsafe/lodestar-config/default";
 
-let chainConfig: Partial<IChainConfig>;
-let genesisValidatorsRoot: Uint8Array;
+// dummy test root
+let genesisValidatorsRoot: Uint8Array = new Uint8Array();
 
 const config: IBeaconConfig = createIBeaconConfig(chainConfig, genesisValidatorsRoot);
 

packages/config/package.json

@@ -30,7 +30,8 @@
     "lint": "eslint --color --ext .ts src/",
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
-    "test:unit": "nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'"
+    "test:unit": "nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "repository": {
     "type": "git",

packages/db/package.json

@@ -34,7 +34,8 @@
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
     "test": "yarn test:unit",
-    "test:unit": "mocha 'test/unit/**/*.test.ts'"
+    "test:unit": "mocha 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "dependencies": {
     "@chainsafe/lodestar-config": "^0.26.0",

packages/fork-choice/package.json

@@ -35,7 +35,8 @@
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
     "test": "yarn test:unit",
-    "test:unit": "mocha --colors -r ts-node/register 'test/unit/**/*.test.ts'"
+    "test:unit": "mocha --colors -r ts-node/register 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "dependencies": {
     "@chainsafe/lodestar-beacon-state-transition": "^0.26.0",

packages/light-client/package.json

@@ -33,7 +33,8 @@
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
     "test": "yarn test:unit && yarn test:e2e",
-    "test:unit": "LODESTAR_PRESET=minimal nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'"
+    "test:unit": "LODESTAR_PRESET=minimal nyc --cache-dir .nyc_output/.cache -e .ts mocha 'test/unit/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "dependencies": {
     "@chainsafe/abort-controller": "^3.0.1",

packages/lodestar/package.json

@@ -40,7 +40,8 @@
     "test:sim": "mocha 'test/sim/**/*.test.ts'",
     "test:sim:singleThread": "mocha 'test/sim/singleNodeSingleThread.test.ts'",
     "test:sim:singleThreadMultiNode": "mocha 'test/sim/multiNodeSingleThread.test.ts'",
-    "test:sim:multiThread": "mocha 'test/sim/multiNodeMultiThread.test.ts'"
+    "test:sim:multiThread": "mocha 'test/sim/multiNodeMultiThread.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "dependencies": {
     "@chainsafe/abort-controller": "^3.0.1",

packages/params/README.md

@@ -29,11 +29,13 @@ The Lodestar params package contains several items used in all downstream Lodest
 
 Many downstream components are namespaced on fork names, or otherwise rely on knowing the fork names ahead of time. The Lodestar params package exports an enum `ForkName` the enumerates all known fork names.
 
-```ts
+```typescript
 import {ForkName} from "@chainsafe/lodestar-params";
 
-let f: ForkName;
-switch (f) {
+// dummy data
+let forkName = "phase0";
+
+switch (forkName) {
   case ForkName.phase0:
   case ForkName.altair:
   default:
@@ -44,7 +46,7 @@ switch (f) {
 
 All constants defined in the spec are exported verbatim.
 
-```ts
+```typescript
 import {GENESIS_SLOT} from "@chainsafe/lodestar-params";
 ```
 
@@ -54,7 +56,7 @@ Presets are "constants"-ish defined in the spec that can only be configured at b
 
 The active preset is exported under the `ACTIVE_PRESET` named export.
 
-```ts
+```typescript
 import {ACTIVE_PRESET, SLOTS_PER_EPOCH} from "@chainsafe/lodestar-params";
 ```
 

packages/params/package.json

@@ -31,7 +31,8 @@
     "lint:fix": "yarn run lint --fix",
     "test": "yarn run check-types",
     "test:unit": "mocha 'test/unit/**/*.test.ts'",
-    "test:e2e": "mocha 'test/e2e/**/*.test.ts'"
+    "test:e2e": "mocha 'test/e2e/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "repository": {
     "type": "git",

packages/spec-test-util/package.json

@@ -33,7 +33,8 @@
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
-    "test:e2e": "mocha 'test/e2e/**/*.test.ts'"
+    "test:e2e": "mocha 'test/e2e/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "repository": {
     "type": "git",

packages/types/README.md

@@ -29,7 +29,7 @@ Lodestar types are all defined as typescript interfaces. These interfaces can be
 
 These interfaces are accessible via named exports.
 
-```ts
+```typescript
 import {Epoch} from "@chainsafe/lodestar-types";
 
 const x: Epoch = 5;
@@ -39,7 +39,7 @@ const x: Epoch = 5;
 
 Lodestar types are also defined as SSZ objects. These "Type" objects provide convenient methods to perform SSZ operations (serialization / deserialization / merkleization/etc). The library exports a singleton object containing all SSZ objects.
 
-```ts
+```typescript
 import {Type} from "@chainsafe/ssz";
 import {ssz, Epoch} from "@chainsafe/lodestar-types";
 
@@ -52,7 +52,7 @@ const e = EpochType.defaultValue();
 
 Lodestar types support multiple different consensus forks. In order to easily differentiate types that may change across forks, types are organized in namespaces according to the fork in which they're introduced. Types introduced in phase 0 are available under the `phase0` namespace. Types introduced in altair are available under the `altair` namespace.
 
-```ts
+```typescript
 import {altair, phase0, ssz} from "@chainsafe/lodestar-types";
 
 const phase0State: phase0.BeaconState = ssz.phase0.BeaconState.defaultValue();
@@ -61,15 +61,15 @@ const altairState: altair.BeaconState = ssz.altair.BeaconState.defaultValue();
 
 Primitive types are directly available without a namespace.
 
-```ts
+```typescript
 import {Epoch, ssz} from "@chainsafe/lodestar-types";
 
 const epoch: Epoch = ssz.Epoch.defaultValue();
 ```
 
 In some cases, we need interfaces that accept types across all forks, eg: when the fork is not known ahead of time. Typescript interfaces for this purpose are exported under the `allForks` namespace. SSZ Types typed to these interfaces are also provided under an `allForks` namespace, but keyed by `ForkName`.
 
-```ts
+```typescript
 import {ForkName} from "@chainsafe/lodestar-params";
 import {allForks, ssz} from "@chainsafe/lodestar-types";
 

packages/types/package.json

@@ -32,7 +32,8 @@
     "check-types": "tsc",
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
-    "test:unit": "mocha 'test/**/*.test.ts'"
+    "test:unit": "mocha 'test/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "types": "lib/index.d.ts",
   "dependencies": {

packages/utils/package.json

@@ -33,7 +33,8 @@
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
     "pretest": "yarn run check-types",
-    "test:unit": "mocha 'test/**/*.test.ts'"
+    "test:unit": "mocha 'test/**/*.test.ts'",
+    "check-readme": "typescript-docs-verifier"
   },
   "types": "lib/index.d.ts",
   "dependencies": {

packages/validator/package.json

@@ -33,7 +33,8 @@
     "test": "yarn test:unit",
     "test:e2e": "yarn run download-test-cases && mocha 'test/e2e/**/*.test.ts'",
     "download-test-cases": "node -r ts-node/register test/e2e/slashing-protection-interchange-tests/downloadTests.ts",
-    "coverage": "codecov -F lodestar-validator"
+    "coverage": "codecov -F lodestar-validator",
+    "check-readme": "typescript-docs-verifier"
   },
   "repository": {
     "type": "git",