Add TypeScript and general refactor

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+- package-ecosystem: npm
+  directory: "/"
+  schedule:
+    interval: monthly
+    time: "03:00"
+  open-pull-requests-limit: 10
+  reviewers:
+  - andreogle

.github/workflows/continuous-build.yml

@@ -0,0 +1,57 @@
+name: Continuous Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone @api3/chains
+        uses: actions/checkout@v3
+
+      - name: Check hyperlinks
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+
+  lint-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone @api3/chains
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'yarn'
+
+      - name: Get yarn cache directory path
+        id: deps-cache-dir-path
+        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v3
+        id: deps-cache
+        with:
+          path: ${{ steps.deps-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Install Dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run Validations
+        run: yarn validate
+
+  required-checks-passed:
+    name: All required checks passed
+    runs-on: ubuntu-latest
+    needs: [documentation, lint-test]
+    steps:
+      - run: exit 0
+

.gitignore

@@ -1,3 +1,4 @@
-node_modules
-
 .env
+*.env
+dist/
+node_modules/

.husky/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+yarn validate:chains
+yarn lint

.prettierignore

@@ -0,0 +1,14 @@
+# NOTE: Keep in sync with .gitignore
+
+# Dependencies
+/node_modules
+
+# Build files
+/coverage
+/dist
+
+# Logs
+*.log
+
+# IDEs
+.vscode

.prettierrc

@@ -0,0 +1,22 @@
+{
+  "bracketSpacing": true,
+  "printWidth": 120,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "useTabs": false,
+  "overrides": [
+    {
+      "files": "*.ts",
+      "options": {
+        "parser": "typescript"
+      }
+    },
+    {
+      "files": "*.md",
+      "options": {
+        "parser": "markdown",
+        "proseWrap": "always"
+      }
+    }
+  ]
+}

README.md

@@ -1,18 +1,37 @@
 # @api3/chains
 
-> A single source of truth for chain-related information
+> The single source of truth for chain-related information
 
-# Notes
+- [Notes](#notes)
+  - [General](#general)
+  - [Deployment](#deployment)
+  - [hardhat-etherscan](#hardhat-etherscan)
+- [API](#api)
+  - [CHAINS](#chains)
+  - [getChainByAlias](#getchainbyalias)
+  - [hardhatConfigNetworks](#hardhatconfignetworks)
+  - [hardhatEtherscan](#hardhatetherscan)
+  - [getEnvVariables](#getenvvariables)
+  - [Types](#types)
+- [Scripts](#scripts)
+    - [chains:generate](#chainsgenerate)
+    - [chains:rename](#chainsrename)
+    - [env:write](#envwrite)
+- [Development](#development)
+    - [Validation](#validation)
+- [Building](#building)
 
-## General
+## Notes
+
+### General
 
 - `gnosis-testnet` provider may return an invalid gas price.
 
-## Deployment
+### Deployment
 
 - `metis-goerli-testnet` and `metis` do not support deterministic deployment.
 
-## hardhat-etherscan
+### hardhat-etherscan
 
 - `hardhat-etherscan` requires us to use a dummy API key with Blockscout block explorer APIs.
   We use `"DUMMY_VALUE"` but it could have been anything else.
@@ -24,3 +43,165 @@
 - `gnosis-testnet` block explorer contract verification API does not work.
 
 - `rsk` and `rsk-testnet` block explorers do not have contract verification APIs.
+
+## API
+
+The following variables/functions are exported from this package
+
+### CHAINS
+
+The single source of truth for the list of supported chains. A static array of `Chain` objects.
+
+```ts
+import { CHAINS } from '@api3/chains';
+console.log(CHAINS);
+/* 
+[
+  {
+    name: 'Arbitrum testnet',
+    alias: 'arbitrum-goerli-testnet',
+    id: '421613',
+    ...
+  },
+  ...
+]   
+*/
+```
+
+### getChainByAlias
+
+Returns a single `Chain` record found by it's alias. Throws an error if the `Chain` is not found.
+
+```ts
+import { getChainByAlias } from '@api3/chains';
+console.log(getChainByAlias('ethereum'));
+/*
+{
+  "name": "Ethereum",
+  "alias": "ethereum",
+  "id": "1",
+  ...
+}
+*/
+```
+
+### hardhatConfigNetworks
+
+Returns an object where the key is each chain's alias and the value is an object that can be used with [hardhat](https://hardhat.org).
+
+```ts
+import { hardhatConfigNetworks } from '@api3/chains';
+console.log(hardhatConfigNetworks());
+/*
+{
+  "arbitrum-goerli-testnet": {
+      accounts: { mnemonic: '' },
+      chainId: '421613',
+      url: 'https://...',
+  },
+  ...
+}
+*/
+```
+
+### hardhatEtherscan
+
+Returns an object that can be used with Etherscan.
+
+```ts
+import { hardhatEtherscan } from '@api3/chains';
+console.log(hardhatEtherscan())
+/*
+{
+  apiKey: {
+    'arbitrumGoerli': { ... }
+  },
+  customChains: [
+    ...
+  ]
+}
+*/
+```
+
+### getEnvVariables
+
+Returns an array of expected environment variable names for chains that have an API key required for the explorer.
+
+```ts
+import { getEnvVariables } from '@api3/chains';
+console.log(getEnvVariables());
+/*
+[
+  'MNEMONIC',
+  'ETHERSCAN_API_KEY_arbitrum-goerli-testnet',
+  ...
+]
+*/
+```
+
+### Types
+
+Types are also exported and can be found in `src/types.ts`. Types are generated from [zod](https://github.com/colinhacks/zod) schemas. These schemas are also used to validate each chain.
+
+## Scripts
+
+The following utility scripts are available
+
+### chains:generate
+
+Generates the latest `CHAINS` array and outputs the file to `src/generated/chains.ts`
+
+```sh
+yarn chains:generate
+```
+
+### chains:rename
+
+Renames each JSON file using the `alias` as the filename.
+
+```sh
+yarn chains:rename
+```
+
+### env:write
+
+Generates the default content for a `.env` file using the output of `getEnvVariables` as the keys.
+
+```sh
+yarn env:write --path .env
+```
+
+## Development
+
+This project works by combining the various JSON files defined in the `chains/` directory into a single generated TypeScript file. This file is then validated to ensure that each chain description conforms to specific requirements. The TypeScript file is generated by running any of these commands
+
+```sh
+yarn chains:generate
+
+# Alternatively, watch the chains/ directory and regenerate on file change
+yarn dev
+```
+
+### Validation
+
+Validations can be run with the following commands.
+
+```sh
+# Validate each chain JSON file conforms to the zod schemas
+yarn validate:chains
+
+# Validate each chain's provider URL is correct and working
+yarn validate:providers
+
+# Run all validations synchronously
+yarn validate
+```
+
+## Building
+
+The TypeScript project can be compiled by running the following command. This regenerates the latest CHAINS array from the JSON files first, before running `tsc`. Files are output in the `dist/` directory
+
+```sh
+yarn build
+```
+

package.json

@@ -2,19 +2,44 @@
   "name": "@api3/chains",
   "license": "MIT",
   "version": "1.4.0",
+  "author": "API3 DAO",
   "private": false,
-  "main": "src/index",
+  "main": "./dist/index.js",
+  "repository": "[email protected]:api3dao/chains",
+  "bugs": {
+    "url": "https://github.com/api3dao/chains/issues"
+  },
   "files": [
-    "chains",
+    "dist",
     "src"
   ],
   "scripts": {
-    "check-provider": "node scripts/check-provider",
+    "build": "yarn clean && yarn chains:generate && tsc -p tsconfig.build.json",
+    "clean": "rimraf ./dist",
+    "dev": "ts-node scripts/generate-chains.ts --watch",
+    "chains:generate": "ts-node scripts/generate-chains.ts",
+    "chains:rename": "ts-node scripts/rename-chain-file.ts",
+    "env:write": "ts-node scripts/write-env-variables.ts",
+    "lint": "exit 0",
+    "prepare": "husky install",
+    "prepublishOnly": "yarn validate:chains",
     "prettier": "prettier --write \"./**/*.{js,md,json}\"",
-    "rename-chain-files": "node scripts/rename-chain-files"
+    "validate": "yarn validate:chains && yarn validate:providers",
+    "validate:chains": "ts-node scripts/validate-chains.ts",
+    "validate:providers": "ts-node scripts/validate-providers.ts"
+  },
+  "dependencies": {
+    "zod": "^3.21.4"
   },
   "devDependencies": {
-    "ethers": "^6.0.8",
-    "prettier": "^2.8.4"
+    "@types/node": "^18.15.11",
+    "@types/prettier": "^2.7.2",
+    "chokidar": "^3.5.3",
+    "ethers": "^6.2.3",
+    "husky": "^8.0.3",
+    "prettier": "^2.8.4",
+    "rimraf": "^4.4.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.3"
   }
 }