init

.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "root": true,
+  "extends": [
+    "airbnb-base",
+    "airbnb-typescript/base",
+    "prettier",
+    "plugin:prettier/recommended"
+  ],
+  "plugins": ["@typescript-eslint", "prettier"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "rules": {
+    "no-console": "off",
+    "prettier/prettier": "error",
+    "import/prefer-default-export": "off",
+    "import/extensions": ["off"],
+    "max-classes-per-file": "off"
+  }
+}

.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.yarn/*
+node_modules/
+
+.env
+
+dist/
+archives/
+data/
+
+*.tsbuildinfo

.prettierrc.json

@@ -0,0 +1,9 @@
+{
+    "arrowParens": "always",
+    "endOfLine": "lf",
+    "printWidth": 80,
+    "semi": false,
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "all"
+  }

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Ethereum Name Service (ENS)
+Copyright (c) 2022 ENS Labs Limited
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1 +1,140 @@
-# ens-test-env
+# ens-test-env
+
+## How it works
+
+The testing environment used here is implemented in the stateless and stateful tests for ENS app.
+The environment consists of two parts: the ganache Ethereum node, and the docker graph instance.
+Which environment type you use is dependent on your testing circumstances.
+
+## Configuration
+
+There should be a file named `ens-test-env.config.js` in your project's root directory.
+You can add a JSDoc type import to import the config type.
+
+```js
+/**
+ * @type {import('@ensdomains/ens-test-env').ENSTestEnvConfig}
+ **/
+module.exports = {
+  deployCommand: 'yarn hardhat deploy',
+  tenderly: {
+    user: 'ens',
+    project: 'core',
+    key: 'tenderly-key',
+  },
+  archive: {
+    subgraphId: 'QmXxAE7Urtv6TPa8o8XmPwLVQNbH6r35hRKHP63udTxTNa',
+    epochTime: 1646894980,
+    blockNumber: 12066620,
+    baseUrl: 'https://storage.googleapis.com/ens-manager-build-data',
+    network: 'mainnet',
+  },
+  docker: {
+    file: './docker-compose.yml',
+    sudo: false,
+  },
+  ethereum: {
+    chain: {
+      chainId: 0,
+    },
+    fork: {
+      url: 'https://example.com',
+    },
+    wallet: {
+      mnemonic: 'test test test test test test test test test test test junk',
+      unlockedAccounts: ['0x0000000000000000000000000000000000000000'],
+    },
+  },
+  graph: {
+    bypassLocal: false,
+  },
+  scripts: [
+    {
+      command: 'example',
+      name: 'example',
+      prefixColor: 'blue.bold',
+      cwd: path.resolve('./'),
+      finishOnExit: true,
+      waitForGraph: true,
+    },
+  ],
+  paths: {
+    archives: './archives',
+    data: './data',
+  },
+}
+```
+
+## Environment Types
+
+### Stateless
+
+For most testing situations you can use the default settings, which will create a fresh mainnet
+fork from a specified block as well as deploying a fresh subgraph with the same specified block
+as it's start block.
+
+Tests should ideally be designed to be stateless where possible, which entails not using hardcoded
+addresses and not relying on any specific blockchain/graph state. This allows for a much higher
+test reliability and low maintenance.
+
+### Stateful
+
+Some tests may require a specific existing state, for example if a test relies on an old deployment
+of a contract which can no longer be accurately replicated from a fresh mainnet fork. The stateful
+environment uses pre-existing subgraph data at a specified block to allow full state access prior
+to the mainnet fork.
+
+The stateful environment can also be used to more closely replicate a production environment for
+true full end-to-end tests. You may also want to use this environment for testing with your own
+personal wallet without using mainnet.
+
+The downside of using the stateful environment is that a test can potentially become unreliable if
+one of it's dependencies changes. Alongside reliability, running a stateful test most of the time
+will require access to a specific private key. Given this, you should try to avoid writing stateful
+tests wherever possible.
+
+## Contract deployments
+
+Contract deployments are a small but necessary part of testing, you can deploy contracts to
+both stateless and stateful environments. After the locally tested contract is deployed, the
+deployment script should be left in the repo to serve as an archive.
+
+## Updating the graph-node dataset
+
+Generally, you will want to set a graft variable in the `subgraph.yaml` file for the subgraph. You
+can find more about the ENS subgraph [here](https://github.com/ensdomains/ens-subgraph). You'll also
+documentation for grafting available [here](https://thegraph.com/docs/en/developer/create-subgraph-hosted/#grafting-onto-existing-subgraphs).
+
+To update the graph-node dataset, the BLOCK_HEIGHT variable must be changed within the `.env` file.
+It should be set to the same value as the graft block.
+
+If the dataset is a dependency for a local test, you will need to first let your local graph-node
+dataset update so that your test can pass.
+
+Once your data is up to date, you can run
+
+```bash
+yarn ens-test-env data --compress
+```
+
+in this directory, which will give you a archive file for your dataset.
+
+### Dataset naming scheme
+
+```js
+const file = `data_${BLOCK_HEIGHT}_${SUBGRAPH_ID}_${EPOCH_TIME}_${NETWORK}.archive`
+// e.g. data_14119046_QmTmU4syjQb8gfNq8TCQGv441qp2zQMNKnQ4smjKhpLQ6F_1643850493_ropsten.archive.tar.lz4
+```
+
+## Running the environment
+
+After this you can run:
+
+```bash
+# Start
+yarn ens-test-env start
+# Load data only
+yarn ens-test-env data --load
+# Export generated data
+yarn ens-test-env data --compress
+```

package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ensdomains/ens-test-env",
+  "type": "module",
+  "version": "0.5.0-beta.1",
+  "files": [
+    "src"
+  ],
+  "types": "src/index.d.ts",
+  "scripts": {
+    "ver": "pnpm version --no-workspaces-update",
+    "publish:local": "yalc publish . --push --up"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ethersproject/wallet": "^5.6.0",
+    "ansi-colors": "^4.1.1",
+    "cli-progress": "^3.10.0",
+    "commander": "^9.3.0",
+    "concurrently": "^7.1.0",
+    "docker-compose": "^0.24.7",
+    "dotenv": "^16.0.1",
+    "js-yaml": "^4.1.0",
+    "lz4": "^0.6.5",
+    "progress-stream": "^2.0.0",
+    "tar-fs": "^2.1.1",
+    "wait-on": "^6.0.1"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.7.5",
+    "@typescript-eslint/parser": "^6.7.5",
+    "eslint": "^8.51.0",
+    "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-airbnb-typescript": "^16.1.2",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "prettier": "^2.8.8",
+    "ts-node": "^10.7.0",
+    "typescript": "^5.3.2"
+  },
+  "preferUnplugged": true,
+  "bin": "./src/index.js"
+}