clean up lib and move docs

Author: skudasov

book/src/SUMMARY.md

@@ -45,5 +45,13 @@
   - [Components](developing/developing_components.md)
 - [Releasing modules](releasing_modules.md)
 
+---
+- [Lib (Legacy, *Deprecated*)](lib.md)
+    - [Blockchain](lib/blockchain.md)
+    - [Kubernetes](lib/k8s/KUBERNETES.md)
+    - [K8s Remote Run](lib/k8s/REMOTE_RUN.md)
+    - [K8s Tutorial](lib/k8s/TUTORIAL.md)
+    - [Config](lib/config/config.md)
+
 ---
 - [Build info](build_info.md)

book/src/lib.md

@@ -0,0 +1,38 @@
+# Blockchain Clients
+
+This folder contains the bulk of code that handles integrating with different EVM chains. If you're looking to run tests on a new EVM chain, and are having issues with the default implementation, you've come to the right place.
+
+### Some Terminology
+
+- [L2 Chain](https://ethereum.org/en/layer-2/): A Layer 2 chain "branching" off Ethereum.
+- [EVM](https://ethereum.org/en/developers/docs/evm/): Ethereum Virtual Machine that underpins the Ethereum blockchain.
+- [EVM Compatible](https://blog.thirdweb.com/evm-compatible-blockchains-and-ethereum-virtual-machine/#:~:text=What%20does%20'EVM%20compatibility'%20mean,significant%20changes%20to%20their%20code.): A chain that has some large, underlying differences from how base Ethereum works, but can still be interacted with largely the same way as Ethereum.
+- [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559): The Ethereum Improvement Proposal that changed how gas fees are calculated and paid on Ethereum
+- Legacy Transactions: Transactions that are sent using the old gas fee calculation method, the one used before EIP-1559.
+- Dynamic Fee Transaction: Transactions that are sent using the new gas fee calculation method, the one used after EIP-1559.
+
+## How Client Integrations Work
+
+In order to test Chainlink nodes, the `chainlink-testing-framework` needs to be able to interact with the chain that the node is running on. This is done through the `blockchain.EVMClient` interface. The `EVMClient` interface is a wrapper around [geth](https://geth.ethereum.org/) to interact with the blockchain. We conduct all our testing blockchain operations through this wrapper, like sending transactions and monitoring on-chain events. The primary implementation of this wrapper is built for [Ethereum](./ethereum.go). Most others, like the [Metis](./metis.go) and [Optimism](./optimism.go) integrations, extend and modify the base Ethereum implementation.
+
+## Do I Need a New Integration?
+
+If you're reading this, probably. The default EVM integration is designed to work with mainnet Ethereum, which covers most other EVM chain interactions, but it's not guaranteed to work with all of them. If you're on a new chain and the test framework is throwing errors while doing basic things like send transactions, receive new headers, or deploy contracts, you'll likely need to create a new integration. The most common issue with new chains (especially L2s) is gas estimations and lack of support for dynamic transactions.
+
+## Creating a New Integration
+
+Take a look at the [Metis](./metis.go) integration as an example. Metis is an L2, EVM compatible chain. It's largely the same as the base Ethereum integration, so we'll extend from that.
+
+```go
+type MetisMultinodeClient struct {
+  *EthereumMultinodeClient
+}
+
+type MetisClient struct {
+  *EthereumClient
+}
+```
+
+Now we need to let other libraries (like our tests in the main Chainlink repo) that this integration exists. So we add the new implementation to the [known_networks.go](./known_networks.go) file. We can then add that network to our tests' own [known_networks.go](https://github.com/smartcontractkit/chainlink/blob/develop/integration-tests/known_networks.go) file (it's annoying, there are plans to simplify).
+
+Now our Metis integration is the exact same as our base Ethereum one, which doesn't do us too much good. I'm assuming you came here to make some changes, so first let's find out what we need to change. This is a mix of reading developer documentation on the chain you're testing and trial and error. Mostly the latter in later stages. In the case of Metis, like many L2s, they [have their own spin on gas fees](https://docs.metis.io/dev/protocol-in-detail/transaction-fees-on-the-metis-platform). They also only support Legacy transactions. So we'll need to override any methods that deal with gas estimations, `Fund`, `DeployContract`, and `ReturnFunds`.

book/src/lib/blockchain.md

@@ -0,0 +1,28 @@
+# Kubernetes
+
+We run our software in Kubernetes.
+
+### Local k3d setup
+
+1. `make install`
+2. (Optional) Install `Lens` from [here](https://k8slens.dev/) or use `k9s` as a low resource consumption alternative from [here](https://k9scli.io/topics/install/)
+   or from source [here](https://github.com/smartcontractkit/helmenv)
+3. Setup your docker resources, 6vCPU/10Gb RAM are enough for most CL related tasks
+4. `make create_cluster`
+5. `make install_monitoring` Note: this will be actively connected to the server, the final log when it is ready is`Forwarding from [::1]:3000 -> 3000` and you can continue with the steps below in another terminal.
+6. Check your contexts with `kubectl config get-contexts`
+7. Switch context `kubectl config use-context k3d-local`
+8. Read [here](README.md) and do some deployments
+9. Open Grafana on `localhost:3000` with `admin/sdkfh26!@bHasdZ2` login/password and check the default dashboard
+10. `make stop_cluster`
+11. `make delete_cluster`
+
+### Typical problems
+
+1. Not enough memory/CPU or cluster is slow
+   Recommended settings for Docker are (Docker -> Preferences -> Resources):
+   - 6 CPU
+   - 10Gb MEM
+   - 50-150Gb Disk
+2. `NodeHasDiskPressure` errors, pods get evicted
+   Use `make docker_prune` to clean up all pods and volumes

book/src/lib/config/config.md

@@ -0,0 +1,37 @@
+## How to run the same environment deployment inside k8s
+
+You can build a `Dockerfile` to run exactly the same environment interactions inside k8s in case you need to run long-running tests
+Base image is [here](Dockerfile.base)
+
+```Dockerfile
+FROM <account number>.dkr.ecr.us-west-2.amazonaws.com/test-base-image:latest
+COPY . .
+RUN env GOOS=linux GOARCH=amd64 go build -o test ./examples/remote-test-runner/env.go
+RUN chmod +x ./test
+ENTRYPOINT ["./test"]
+```
+
+Build and upload it using the "latest" tag for the test-base-image
+
+```bash
+build_test_image tag=someTag
+```
+
+or if you want to specify a test-base-image tag
+
+```bash
+build_test_image tag=someTag base_tag=latest
+```
+
+Then run it
+
+```bash
+# all environment variables with a prefix TEST_ would be provided for k8s job
+export TEST_ENV_VAR=myTestVarForAJob
+# your image to run as a k8s job
+ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
+export ENV_JOB_IMAGE="${ACCOUNT}.dkr.ecr.us-west-2.amazonaws.com/core-integration-tests:v1.1"
+# your example test file to run inside k8s
+# if ENV_JOB_IMAGE is present it will create a job, wait until it finished and get logs
+go run examples/remote-test-runner/env.go
+```