Initial push for zilliqa 2 documentation (#646)

* (feat) Start of zilliqa 2 documentation

* (feat) more formatting
(feat) now pulls versions "live" from the chain.

* (feat) A bit more zq2 documentation
(feat) The ability to build a container to serve zq2 docs

* (feat) more zq2 docs

* (fix) more doc updates.

* (feat) Add links to XBridge

* (fix) Use the right logo for the ZQ2 docs site.

* (feat) Move documentation inside the mkdocs directory.

* (feat) Hopefully one day allow us to connect directly to metamask
(feat) otterscan API details.

* (fix) CICD for zq2 docs site

* (feat) add a coingecko link.

* (feat) CI/CD for stg and production (erm, I hope!)

* (fix) Fixes for trunk

* (fix) Formatting issues to fix trunk check

* (fix) Disable more linters for client-side dependencies.

* (fix) Build stg to test cicd

* (feat) Utterly spurious, but now allows you to translate between bech32 and hex.

* (fix) obInvalidTrunkWarning

* (fix) Keep overrides so that mkdocs can find it

* (fix) Try to quote IMAGE_TAG in the hope of being able to push a latest tag ..

* (fix) Actually ship portal to latest tag.

* (fix) fix managed certs

* (fix) minor prod diffs, not yet relevant (since we don't have a prod release of the z2 docs yet)
(fix) Re-disable cicd-stg

* (fix) make trunk happy

.github/workflows/cicd-prd.yml

@@ -136,7 +136,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        application: [developer-portal, devex, zilliqa-isolated-server]
+        application:
+          [
+            developer-portal,
+            devex,
+            zilliqa-isolated-server,
+            developer-portal-zq2,
+          ]
         include:
           - application: developer-portal
             image_name: developer-portal
@@ -153,6 +159,11 @@ jobs:
             path: products/zilliqa-isolated-server
             tag_length: 8
             tag_latest: true
+          - application: developer-portal-zq2
+            image-name: developer-portal-zq2
+            path: products/developer-portal-zq2
+            tag_length: 8
+            tag_latest: false
     env:
       DOCKER_DOMAIN: asia-docker.pkg.dev
       REGISTRY: asia-docker.pkg.dev/prj-p-devops-services-tvwmrf63/zilliqa-public

.github/workflows/cicd-stg.yml

@@ -128,18 +128,30 @@ jobs:
       id-token: write
       contents: write
     runs-on: ubuntu-22.04
+    # To test deployments, remove the github.ref_name clause: see devops/docs/z2-testing-apps.md - rrw 2024-04-12
     if: github.actor != 'dependabot[bot]' && github.ref_name == 'main'
     name: "Build image with Makefile"
     strategy:
       fail-fast: false
       matrix:
-        application: [developer-portal, devex, zilliqa-isolated-server]
+        application:
+          [
+            developer-portal,
+            developer-portal-zq2,
+            devex,
+            zilliqa-isolated-server,
+          ]
         include:
           - application: developer-portal
             image_name: developer-portal
             path: products/developer-portal
             tag_length: 8
             tag_latest: false
+          - application: developer-portal-zq2
+            image_name: developer-portal-zq2
+            path: products/developer-portal-zq2
+            tag_length: 8
+            tag_latest: true
           - application: devex
             image_name: devex
             path: products/devex

.markdownlint.yaml

@@ -4,3 +4,4 @@ MD024: { allow_different_nesting: true }
 MD030: false
 MD033: false
 MD046: false
+MD025: { front_matter_title: "" }

.trunk/trunk.yaml

@@ -28,6 +28,7 @@ lint:
     - linters: [gitleaks]
       paths:
         - products/laksaj # laksaj contains a lot of embedded testnet privkeys - ignore them.
+        - products/developer-portal-zq2/docs/api # Contains a lot of hashes, etc. that are interpreted as secrets
         - docs/developers/transaction-lifecycle/dev-txn-broadcasting.md # Contains examples.
         - products/bridge/smart-contracts/script/config.ts
         - products/bridge/smart-contracts/script/**/*.s.sol
@@ -39,6 +40,9 @@ lint:
         - products/bridge/bridge-web
     - linters: [ALL]
       paths:
+        - products/developer-portal-zq2/Dockerfile # Annoying, but trunk is now very opinionated on how you write dockerfiles.
+        - products/developer-portal-zq2/docs/js/** # trunk does not know this is looking for metamask in the user's browser.
+        - products/developer-portal-zq2/docs/index.md # contains legitimate empty links
         - needing-organisation/**/*
         - products/devex/public/*.js
         - products/dev-wallet/**

products/developer-portal-zq2/.gitignore

@@ -0,0 +1,2 @@
+# Object files
+obj/**

products/developer-portal-zq2/Dockerfile

@@ -0,0 +1,21 @@
+FROM ubuntu:22.04 AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV NEEDRESTART_MODE=a
+
+RUN apt-get update && apt-get dist-upgrade -y
+RUN apt-get install -y python3 python3-pip --no-install-recommends
+
+COPY .  /build
+RUN pip3 install --no-cache-dir -r /build/requirements.txt
+
+ENV DOC_SOURCE=docs
+WORKDIR /build
+RUN  mkdocs build
+
+FROM nginx:alpine-slim
+
+COPY --from=builder --chown=nginx:nginx /build/site/. /usr/share/nginx/html/.
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]

products/developer-portal-zq2/Makefile

@@ -0,0 +1,47 @@
+.PHONY: all
+all: image/build-and-push
+
+.ONESHELL:
+SHELL := /bin/bash
+.SHELLFLAGS = -ec
+
+ENVIRONMENT ?= dev
+VALID_ENVIRONMENTS := dev stg prd
+
+# Check if the ENVIRONMENT variable is in the list of valid environments
+ifeq ($(filter $(ENVIRONMENT),$(VALID_ENVIRONMENTS)),)
+$(error Invalid value for ENVIRONMENT. Valid values are dev, stg, or prd.)
+endif
+
+
+HERE=$(shell pwd)
+
+DOC_SOURCE=$(HERE)/docs
+export DOC_SOURCE
+
+dev:
+	mkdocs serve
+
+BINDIR=$(HERE)/obj
+HERE_FILES=Dockerfile mkdocs.yaml overrides requirements.txt
+
+# Sadly necessary because we need the docs from .., and using that as the dockerfile context
+# would be a whole world of pain.
+.PHONY: assemble build
+assemble:
+	rm -rf $(BINDIR)
+	mkdir -p $(BINDIR)
+	cp -r $(HERE_FILES) $(BINDIR)
+	cp -r $(DOC_SOURCE) $(BINDIR)
+
+IMAGE_TAG ?= zq2-docs:latest
+
+build:
+	docker buildx build . -t $(IMAGE_TAG)
+
+run-image: build
+	docker run --rm -p 8080:80 "$(IMAGE_TAG)"
+
+## Build and push the Docker image
+image/build-and-push: build
+	docker push "$(IMAGE_TAG)"

products/developer-portal-zq2/cd/base/deployment.yaml

@@ -0,0 +1,29 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: developer-portal-zq2
+  namespace: developer-portal-zq2
+  labels:
+    app.kubernetes.io/name: "developer-portal-zq2"
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: "developer-portal-zq2"
+  strategy:
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: "developer-portal-zq2"
+    spec:
+      containers:
+        - image: developer-portal-zq2
+          name: developer-portal-zq2
+          ports:
+            - containerPort: 80
+          resources:
+            limits:
+              memory: 200Mi
+            requests:
+              memory: 100Mi

products/developer-portal-zq2/cd/base/ingress.yaml

@@ -0,0 +1,31 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: developer-portal-zq2
+  namespace: developer-portal-zq2
+  labels:
+    app.kubernetes.io/name: "developer-portal-zq2"
+  annotations:
+    nginx.ingress.kubernetes.io/rewrite-target: /$2
+spec:
+  rules:
+    - host: localhost
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: developer-portal-zq2
+                port:
+                  number: 80
+    - host: dev-zq2.zilliqa.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: developer-portal-zq2
+                port:
+                  number: 80

products/developer-portal-zq2/cd/base/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - deployment.yaml
+  - svc.yaml
+  - ingress.yaml

products/developer-portal-zq2/cd/base/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: developer-portal-zq2

products/developer-portal-zq2/cd/base/svc.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: developer-portal-zq2
+  namespace: developer-portal-zq2
+  labels:
+    app.kubernetes.io/name: "developer-portal-zq2"
+spec:
+  type: ClusterIP
+  ports:
+    - port: 80
+      targetPort: 80
+      protocol: TCP
+      name: http
+  selector:
+    app.kubernetes.io/name: "developer-portal-zq2"

products/developer-portal-zq2/cd/overlays/production/certificate.yaml

@@ -0,0 +1,7 @@
+apiVersion: networking.gke.io/v1
+kind: ManagedCertificate
+metadata:
+  name: developer-portal-zq2
+spec:
+  domains:
+    - zq2-dev.zilliqa.com

products/developer-portal-zq2/cd/overlays/production/frontend-config.yaml

@@ -0,0 +1,8 @@
+apiVersion: networking.gke.io/v1beta1
+kind: FrontendConfig
+metadata:
+  name: developer-portal-zq2
+spec:
+  redirectToHttps:
+    enabled: true
+    responseCodeName: RESPONSE_CODE

products/developer-portal-zq2/cd/overlays/production/kustomization.yaml

@@ -0,0 +1,27 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+  - certificate.yaml
+  - frontend-config.yaml
+
+patches:
+  - target:
+      kind: Ingress
+      name: developer-portal-zq2
+    patch: |-
+      - op: replace
+        path: "/spec/rules/0/host"
+        value: dev-zq2.zilliqa.com
+      - op: remove
+        path: "/spec/rules/1"
+      - op: replace
+        path: /metadata/annotations
+        value:
+          kubernetes.io/ingress.class: gce
+          kubernetes.io/ingress.global-static-ip-name: dev-zq2-zilliqa-com
+          networking.gke.io/managed-certificates: developer-portal-zq2
+          networking.gke.io/v1beta1.FrontendConfig: developer-portal-zq2
+
+namespace: developer-portal-zq2-prd

products/developer-portal-zq2/cd/overlays/staging/certificate.yaml

@@ -0,0 +1,7 @@
+apiVersion: networking.gke.io/v1
+kind: ManagedCertificate
+metadata:
+  name: stg-zq2-dev
+spec:
+  domains:
+    - stg-zq2-dev.zilstg.dev

products/developer-portal-zq2/cd/overlays/staging/kustomization.yaml

@@ -0,0 +1,26 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+  - certificate.yaml
+
+patches:
+  - target:
+      kind: Ingress
+      name: developer-portal-zq2
+    patch: |-
+      - op: replace
+        path: "/spec/rules/0/host"
+        value: stg-zq2-dev.zilstg.dev
+      - op: replace
+        path: "/spec/rules/1/host"
+        value: stg-zq2-dev.zilliqa.com
+      - op: replace
+        path: /metadata/annotations
+        value:
+          kubernetes.io/ingress.class: gce
+          kubernetes.io/ingress.global-static-ip-name: stg-zq2-dev-zilstg-dev
+          networking.gke.io/managed-certificates: stg-zq2-dev
+
+namespace: developer-portal-zq2-stg

products/developer-portal-zq2/docs/api/erigon/get-header-by-number.md

@@ -0,0 +1,57 @@
+---
+id: api/erigon/erigon_getHeaderByNumber
+title: erigon_getHeaderByNumber
+---
+
+---
+
+- Returns the erigon headers for a given block number
+
+### Example Request
+
+=== "cURL"
+
+    ```shell
+    curl -d '{
+        "id": "1",
+        "jsonrpc": "2.0",
+        "method": "erigon_getHeaderByNumber",
+        "params": [ 1000 ]
+    }' -H "Content-Type: application/json" -X POST "https://api.zq2-devnet.zilliqa.com/"
+    ```
+
+### Example Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "number": "0x3e8",
+    "hash": "0x7dbeae485c26511423301be854c6cdec6b07170427f3270ac1748782f4fe4a8f",
+    "parentHash": "0x71d2d959e0eb73b429686c0c1107e4183f04c0a54752d4fe519a1f0c54ab7cdb",
+    "nonce": "0x0000000000000000",
+    "sha3Uncles": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+    "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "stateRoot": "0xd639a448087e7d087fb2d0fef4a1bd95237a965277dcbf7ee33344384491d409",
+    "receiptsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "miner": "0x768af8c0b4792ed2948186857f1122f3cd6a695d",
+    "difficulty": "0x0",
+    "totalDifficulty": "0x0",
+    "extraData": "0x",
+    "size": "0x0",
+    "gasLimit": "0x501bd00",
+    "gasUsed": "0x0",
+    "timestamp": "0x6602d4bc",
+    "transactions": [],
+    "uncles": []
+  },
+  "id": "1"
+}
+```
+
+### Arguments
+
+| Parameter | Type   | Required | Description               |
+| --------- | ------ | -------- | ------------------------- |
+| `block`   | number | Required | The block number to query |

products/developer-portal-zq2/docs/api/ethereum/eth-rpc.md

@@ -0,0 +1,12 @@
+---
+id: api/ethereum/index
+title: Supported ETH API calls
+---
+
+---
+
+# Ethereum API
+
+We support a subset of the [Ethereum JSON-RPC API methods](https://ethereum.org/en/developers/docs/apis/json-rpc/).
+
+See [endpoints](/endpoints.md) for details of which RPC endpoints are supported by each deployed version of Zilliqa 2.0 (TBD: this information will eventually be extracted here for convenience).