From 2ca65988c3be74680bdb804b5008c349b50fd262 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?=
 <michalina.cienciala@keep.network>
Date: Wed, 19 Apr 2023 12:13:33 +0200
Subject: [PATCH 01/10] Automatically generate contracts documentation

We are creating GH Actions workflows which automatically generates the contracts
documentation in Markdown, based on the functions and the NatSpec-format
comments in the Solidity files stored in the `contracts` folders in
`keep-network/keep-core/solidity/random-beacon` and
`keep-network/keep-core/solidity/ecdsa`. For certain workflow triggers, the
generated documentation will be pushed to the `threshold-network/threshold`
repository, under `./docs/app-development/random-beacon/random-beacon-api` /
`./docs/app-development/ecdsa/ecdsa-api`. As the `.docs` folder is synched with
Threshold docs GitBook space, the pushed docs will be displayed in HTML under
`docs.threshold.network` domain.

There are two main jobs in the workflows:

* `contracts-docs-publish-preview`
* `contracts-docs-publish`

Both call a reusable workflow `reusable-solidity-docs.yml` which resides in the
`keep-network/ci` repository under `.github/workflows`. The jobs differ in
parameters with witch the reusable action is called. The common part of the jobs
is the beginning stage, where the Solidity files are being prepared for Markdown
generation. During that stage the jobs will remove the spaces chars between the
NatSpec comments markers (`///`) and the text of the comment. This is done to
ensure proper rendering of the lists in the output docs and is a default
action made by `reusable-solidity-docs.yml`. Another pre-processing is
running a `sed` command on a `./contracts/bridge/BitcoinTx.sol` that removes
incorrectly used line with `//` blank comment in the middle of section with
NatSpec's `///` comments (which was breaking the formatting of that comment in
Markdown).
Once files are ready, the jobs use Docgen tool to generate the Markdown docs.
The tool needs to be installed in the project and configured in the
`hardhat.config.ts`. The configuration that we use specifies that the docs
should be generated to the `geerated-docs` subfolder, to one single `index.md`
file. The `.sol` files in the `./solidity/contracts/test` folder will be
ignored during generation (those are test/stub contracts which are not used on
Mainnet). A custom template will be used during docs generations. The template
was created based on the default
`https://github.com/OpenZeppelin/solidity-docgen/blob/master/src/themes/markdown/common.hbs`
template, but it removes the cursive from the `@dev` type comments (because the
cursive didn't work well with formatting of the lists).
Once the Docgen is run and the `index.md` file is generated, the jobs will add
a Table of Contents to the file, to improve the navigation. The TOC will be
added by the `markdown-toc` tool and will be generated using `--maxdepth 2`
param, which results in listing all the contract names, but not the functions.
Once the TOC is added, we'll start to see the difference in the behavior of the
jobs.

The `contracts-docs-publish-preview` job is triggered for:
* `pull_request` events, if the PR modifies either files if
  `./solidity/<project>/contracts` or the workflow files itself,
* `push` events, when the push is made to a branch which name starts with
  `releases/mainnet/solidity/` and project's files are modified,
* `workflow_dispatch` events.
The job publishes the generated artifacts as artifacts of the GH Actions
workflow run. For PRs, link to the run with the artifacts will be posted as a PR
comment.

The `contracts-docs-publish` job is triggered for:
* published releases, which names start with `refs/tags/solidity/`.
The job pushes the generated file to the
`./docs/app-development/random-beacon/random-beacon-api` /
`./docs/app-development/ecdsa/ecdsa-api`folder in the
`threshold-network/threshold` repo, to the `main` branch. The `.docs` folder
is synched with the GitBook Threshold documentation, so thanks to the job, the
changes in the contracts should be reflected on the docs.threshold.network.
In order for the job to work, we need to configure a user which will create the
commit The user needs to have right to commit to the
`threshold-network/threshold` repo. We also need to configure following secrets:
- [ ] `THRESHOLD_DOCS_GITHUB_TOKEN`
- [ ] `GPG_PRIVATE_KEY`
- [ ] `GPG_PASSPHRASE`
We're using a GPG key to be able to do verified commits.
---
 .github/workflows/contracts-ecdsa-docs.yml    | 75 +++++++++++++++++++
 .../contracts-random-beacon-docs.yml          | 75 +++++++++++++++++++
 solidity/ecdsa/.prettierignore                |  1 +
 solidity/ecdsa/docgen-templates/common.hbs    | 33 ++++++++
 solidity/ecdsa/hardhat.config.ts              |  7 ++
 solidity/ecdsa/package.json                   |  1 +
 solidity/ecdsa/yarn.lock                      | 42 ++++++++++-
 solidity/random-beacon/.prettierignore        |  1 +
 .../random-beacon/docgen-templates/common.hbs | 33 ++++++++
 solidity/random-beacon/hardhat.config.ts      |  7 ++
 solidity/random-beacon/package.json           |  1 +
 solidity/random-beacon/yarn.lock              | 42 ++++++++++-
 12 files changed, 316 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/contracts-ecdsa-docs.yml
 create mode 100644 .github/workflows/contracts-random-beacon-docs.yml
 create mode 100644 solidity/ecdsa/docgen-templates/common.hbs
 create mode 100644 solidity/random-beacon/docgen-templates/common.hbs

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
new file mode 100644
index 0000000000..8380bd9d10
--- /dev/null
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -0,0 +1,75 @@
+name: Solidity ECDSA docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - releases/mainnet/solidity/**
+    paths:
+      - "solidity/ecdsa/**"
+  release:
+    types:
+      - "published"
+  workflow_dispatch:
+
+jobs:
+  docs-detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      path-filter: ${{ steps.filter.outputs.path-filter }}
+    steps:
+      - uses: actions/checkout@v3
+        if: github.event_name == 'pull_request'
+      - uses: dorny/paths-filter@v2
+        if: github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            path-filter:
+              - './solidity/ecdsa/contracts/**'
+              - './.github/workflows/contracts-ecdsa-docs.yml'
+
+  # This job will be triggered for PRs which modify contracts. It will generate
+  # the archive with contracts documentation in Markdown and attatch it to the
+  # workflow run results. Link to the archive will be posted in a PR comment.
+  # The job will also be run after manual triggering and after pushes to the
+  # `releases/mainnet/solidity/**` branches if there were changes to the
+  # `ecdsa` project.
+  contracts-docs-publish-preview:
+    name: Publish preview of contracts documentation
+    needs: docs-detect-changes
+    if: |
+      github.event_name == 'pull_request'
+        || github.event_name == 'push'
+        || github.event_name == 'workflow_dispatch'
+    uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
+    with:
+      projectSubfolder: /solidity/ecdsa
+      publish: false
+      commentPR: true
+      exportAsGHArtifacts: true
+
+  # This job will be triggered for releases which name starts with
+  # `refs/tags/solidity/`. It will generate contracts documentation in
+  # Markdown and sync it with a specific path of
+  # `threshold-network/threshold` repository. If changes will be detected,
+  # the destination repository will be updated. The commit pushing the
+  # changes will be verified using GPG key.
+  contracts-docs-publish:
+    name: Publish contracts documentation
+    needs: docs-detect-changes
+    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
+    uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
+    with:
+      projectSubfolder: /solidity/ecdsa
+      publish: true
+      verifyCommits: true
+      destinationRepo: threshold-network/threshold
+      destinationFolder: ./docs/app-development/tbtc-v2/ecdsa-api
+      destinationBranch: main
+      userEmail: thesis-valkyrie@users.noreply.github.com
+      userName: Valkyrie
+    secrets:
+      githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
+      gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }}
+      gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }}
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
new file mode 100644
index 0000000000..13110136dc
--- /dev/null
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -0,0 +1,75 @@
+name: Solidity Random Beacon docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - releases/mainnet/solidity/**
+    paths:
+      - "solidity/random-beacon/**"
+  release:
+    types:
+      - "published"
+  workflow_dispatch:
+
+jobs:
+  docs-detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      path-filter: ${{ steps.filter.outputs.path-filter }}
+    steps:
+      - uses: actions/checkout@v3
+        if: github.event_name == 'pull_request'
+      - uses: dorny/paths-filter@v2
+        if: github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            path-filter:
+              - './solidity/random-beacon/contracts/**'
+              - './.github/workflows/contracts-random-beacon-docs.yml'
+
+  # This job will be triggered for PRs which modify contracts. It will generate
+  # the archive with contracts documentation in Markdown and attatch it to the
+  # workflow run results. Link to the archive will be posted in a PR comment.
+  # The job will also be run after manual triggering and after pushes to the
+  # `releases/mainnet/solidity/**` branches if there were changes to the
+  # `random-beacon` project.
+  contracts-docs-publish-preview:
+    name: Publish preview of contracts documentation
+    needs: docs-detect-changes
+    if: |
+      github.event_name == 'pull_request'
+        || github.event_name == 'push'
+        || github.event_name == 'workflow_dispatch'
+    uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
+    with:
+      projectSubfolder: /solidity/random-beacon
+      publish: false
+      commentPR: true
+      exportAsGHArtifacts: true
+
+  # This job will be triggered for releases which name starts with
+  # `refs/tags/solidity/`. It will generate contracts documentation in
+  # Markdown and sync it with a specific path of
+  # `threshold-network/threshold` repository. If changes will be detected,
+  # the destination repository will be updated. The commit pushing the
+  # changes will be verified using GPG key.
+  contracts-docs-publish:
+    name: Publish contracts documentation
+    needs: docs-detect-changes
+    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
+    uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
+    with:
+      projectSubfolder: /solidity/random-beacon
+      publish: true
+      verifyCommits: true
+      destinationRepo: threshold-network/threshold
+      destinationFolder: ./docs/app-development/random-beacon/random-beacon-api
+      destinationBranch: main
+      userEmail: thesis-valkyrie@users.noreply.github.com
+      userName: Valkyrie
+    secrets:
+      githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
+      gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }}
+      gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }}
diff --git a/solidity/ecdsa/.prettierignore b/solidity/ecdsa/.prettierignore
index a3a7d575dc..b9844a0fd1 100644
--- a/solidity/ecdsa/.prettierignore
+++ b/solidity/ecdsa/.prettierignore
@@ -6,4 +6,5 @@ export/
 external/
 hardhat-dependency-compiler/
 typechain/
+docgen-templates/
 export.json
diff --git a/solidity/ecdsa/docgen-templates/common.hbs b/solidity/ecdsa/docgen-templates/common.hbs
new file mode 100644
index 0000000000..564f17b450
--- /dev/null
+++ b/solidity/ecdsa/docgen-templates/common.hbs
@@ -0,0 +1,33 @@
+{{h}} {{name}}
+
+{{#if signature}}
+```solidity
+{{{signature}}}
+```
+{{/if}}
+
+{{{natspec.notice}}}
+
+{{#if natspec.dev}}
+{{{natspec.dev}}}
+{{/if}}
+
+{{#if natspec.params}}
+{{h 2}} Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each params}}
+| {{name}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+
+{{#if natspec.returns}}
+{{h 2}} Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each returns}}
+| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
\ No newline at end of file
diff --git a/solidity/ecdsa/hardhat.config.ts b/solidity/ecdsa/hardhat.config.ts
index 2ab03c16d9..387271acf3 100644
--- a/solidity/ecdsa/hardhat.config.ts
+++ b/solidity/ecdsa/hardhat.config.ts
@@ -9,6 +9,7 @@ import "@tenderly/hardhat-tenderly"
 import "hardhat-contract-sizer"
 import "hardhat-dependency-compiler"
 import "hardhat-gas-reporter"
+import "solidity-docgen"
 
 import "./tasks"
 import { task } from "hardhat/config"
@@ -221,6 +222,12 @@ const config: HardhatUserConfig = {
   typechain: {
     outDir: "typechain",
   },
+  docgen: {
+    outputDir: "generated-docs",
+    templates: "docgen-templates",
+    pages: "single", // `single`, `items` or `files`
+    exclude: ["./test"],
+  },
 }
 
 task(TASK_TEST, "Runs mocha tests").setAction(async (args, hre, runSuper) => {
diff --git a/solidity/ecdsa/package.json b/solidity/ecdsa/package.json
index f5880a5384..ca9bd39b97 100644
--- a/solidity/ecdsa/package.json
+++ b/solidity/ecdsa/package.json
@@ -64,6 +64,7 @@
     "prettier-plugin-solidity": "^1.0.0-beta.19",
     "solhint": "^3.3.6",
     "solhint-config-keep": "github:keep-network/solhint-config-keep",
+    "solidity-docgen": "^0.6.0-beta.35",
     "ts-node": "^10.4.0",
     "typechain": "^6.1.0",
     "typescript": "^4.5.4"
diff --git a/solidity/ecdsa/yarn.lock b/solidity/ecdsa/yarn.lock
index 4e95365aa5..371146537a 100644
--- a/solidity/ecdsa/yarn.lock
+++ b/solidity/ecdsa/yarn.lock
@@ -6087,6 +6087,18 @@ growl@1.10.5:
   resolved "https://registry.yarnpkg.com/growl/-/growl-1.10.5.tgz#f2735dc2283674fa67478b10181059355c369e5e"
   integrity sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA==
 
+handlebars@^4.7.7:
+  version "4.7.7"
+  resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.7.tgz#9ce33416aad02dbd6c8fafa8240d5d98004945a1"
+  integrity sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==
+  dependencies:
+    minimist "^1.2.5"
+    neo-async "^2.6.0"
+    source-map "^0.6.1"
+    wordwrap "^1.0.0"
+  optionalDependencies:
+    uglify-js "^3.1.4"
+
 har-schema@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/har-schema/-/har-schema-2.0.0.tgz#a94c2224ebcac04782a0d9035521f24735b7ec92"
@@ -8084,6 +8096,11 @@ negotiator@0.6.3:
   resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.3.tgz#58e323a72fedc0d6f9cd4d31fe49f51479590ccd"
   integrity sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==
 
+neo-async@^2.6.0:
+  version "2.6.2"
+  resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f"
+  integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==
+
 next-tick@^1.1.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/next-tick/-/next-tick-1.1.0.tgz#1836ee30ad56d67ef281b22bd199f709449b35eb"
@@ -9820,11 +9837,24 @@ solidity-ast@^0.4.15:
   resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.31.tgz#c63e42f894cd047826a05dbb8d1e1dfc17282d39"
   integrity sha512-kX6o4XE4ihaqENuRRTMJfwQNHoqWusPENZUlX4oVb19gQdfi7IswFWnThONHSW/61umgfWdKtCBgW45iuOTryQ==
 
+solidity-ast@^0.4.38:
+  version "0.4.46"
+  resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.46.tgz#d0745172dced937741d07464043564e35b147c59"
+  integrity sha512-MlPZQfPhjWXqh7YxWcBGDXaPZIfMYCOHYoLEhGDWulNwEPIQQZuB7mA9eP17CU0jY/bGR4avCEUVVpvHtT2gbA==
+
 solidity-comments-extractor@^0.0.7:
   version "0.0.7"
   resolved "https://registry.yarnpkg.com/solidity-comments-extractor/-/solidity-comments-extractor-0.0.7.tgz#99d8f1361438f84019795d928b931f4e5c39ca19"
   integrity sha512-wciNMLg/Irp8OKGrh3S2tfvZiZ0NEyILfcRCXCD4mp7SgK/i9gzLfhY2hY7VMCQJ3kH9UB9BzNdibIVMchzyYw==
 
+solidity-docgen@^0.6.0-beta.35:
+  version "0.6.0-beta.35"
+  resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.35.tgz#174d7fe54efa8b10f7d3cbe0dfc40e52e11bf867"
+  integrity sha512-9QdwK1THk/MWIdq1PEW/6dvtND0pUqpFTsbKwwU9YQIMYuRhH1lek9SsgnsGGYtdJ0VTrXXcVT30q20a8Y610A==
+  dependencies:
+    handlebars "^4.7.7"
+    solidity-ast "^0.4.38"
+
 source-map-resolve@^0.5.0:
   version "0.5.3"
   resolved "https://registry.yarnpkg.com/source-map-resolve/-/source-map-resolve-0.5.3.tgz#190866bece7553e1f8f267a2ee82c606b5509a1a"
@@ -9869,7 +9899,7 @@ source-map@^0.5.6, source-map@^0.5.7:
   resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.5.7.tgz#8a039d2d1021d22d1ea14c80d8ea468ba2ef3fcc"
   integrity sha1-igOdLRAh0i0eoUyA2OpGi6LvP8w=
 
-source-map@^0.6.0:
+source-map@^0.6.0, source-map@^0.6.1:
   version "0.6.1"
   resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263"
   integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==
@@ -10708,6 +10738,11 @@ typical@^5.2.0:
   resolved "https://registry.yarnpkg.com/typical/-/typical-5.2.0.tgz#4daaac4f2b5315460804f0acf6cb69c52bb93066"
   integrity sha512-dvdQgNDNJo+8B2uBQoqdb11eUCE1JQXhvjC/CZtgvZseVd5TYMXnq0+vuUemXbd/Se29cTaUuPX3YIc2xgbvIg==
 
+uglify-js@^3.1.4:
+  version "3.17.4"
+  resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.17.4.tgz#61678cf5fa3f5b7eb789bb345df29afb8257c22c"
+  integrity sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==
+
 ultron@~1.1.0:
   version "1.1.1"
   resolved "https://registry.yarnpkg.com/ultron/-/ultron-1.1.1.tgz#9fe1536a10a664a65266a1e3ccf85fd36302bc9c"
@@ -11540,6 +11575,11 @@ word-wrap@^1.2.3, word-wrap@~1.2.3:
   resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.3.tgz#610636f6b1f703891bd34771ccb17fb93b47079c"
   integrity sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==
 
+wordwrap@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb"
+  integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==
+
 wordwrapjs@^4.0.0:
   version "4.0.1"
   resolved "https://registry.yarnpkg.com/wordwrapjs/-/wordwrapjs-4.0.1.tgz#d9790bccfb110a0fc7836b5ebce0937b37a8b98f"
diff --git a/solidity/random-beacon/.prettierignore b/solidity/random-beacon/.prettierignore
index 70244c3170..91e185b818 100644
--- a/solidity/random-beacon/.prettierignore
+++ b/solidity/random-beacon/.prettierignore
@@ -5,4 +5,5 @@ deployments/
 external/
 hardhat-dependency-compiler/
 typechain/
+docgen-templates/
 export.json
diff --git a/solidity/random-beacon/docgen-templates/common.hbs b/solidity/random-beacon/docgen-templates/common.hbs
new file mode 100644
index 0000000000..564f17b450
--- /dev/null
+++ b/solidity/random-beacon/docgen-templates/common.hbs
@@ -0,0 +1,33 @@
+{{h}} {{name}}
+
+{{#if signature}}
+```solidity
+{{{signature}}}
+```
+{{/if}}
+
+{{{natspec.notice}}}
+
+{{#if natspec.dev}}
+{{{natspec.dev}}}
+{{/if}}
+
+{{#if natspec.params}}
+{{h 2}} Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each params}}
+| {{name}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+
+{{#if natspec.returns}}
+{{h 2}} Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each returns}}
+| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
\ No newline at end of file
diff --git a/solidity/random-beacon/hardhat.config.ts b/solidity/random-beacon/hardhat.config.ts
index d5bec3bc4b..dd34526f3a 100644
--- a/solidity/random-beacon/hardhat.config.ts
+++ b/solidity/random-beacon/hardhat.config.ts
@@ -10,6 +10,7 @@ import "hardhat-contract-sizer"
 import "@typechain/hardhat"
 import "hardhat-dependency-compiler"
 import "./tasks"
+import "solidity-docgen"
 
 import { task } from "hardhat/config"
 
@@ -192,6 +193,12 @@ const config: HardhatUserConfig = {
     currency: "USD",
     coinmarketcap: process.env.COINMARKETCAP_API_KEY,
   },
+  docgen: {
+    outputDir: "generated-docs",
+    templates: "docgen-templates",
+    pages: "single", // `single`, `items` or `files`
+    exclude: ["./test"],
+  },
 }
 
 task("check-accounts-count", "Checks accounts count").setAction(async () => {
diff --git a/solidity/random-beacon/package.json b/solidity/random-beacon/package.json
index f99d432039..dae0bec187 100644
--- a/solidity/random-beacon/package.json
+++ b/solidity/random-beacon/package.json
@@ -66,6 +66,7 @@
     "prettier-plugin-solidity": "^1.0.0-beta.18",
     "solhint": "^3.3.6",
     "solhint-config-keep": "github:keep-network/solhint-config-keep",
+    "solidity-docgen": "^0.6.0-beta.35",
     "ts-node": "^10.2.1",
     "typechain": "^7.0.0",
     "typescript": "^4.4.3"
diff --git a/solidity/random-beacon/yarn.lock b/solidity/random-beacon/yarn.lock
index 3dbaf6c5d1..b2f058cc79 100644
--- a/solidity/random-beacon/yarn.lock
+++ b/solidity/random-beacon/yarn.lock
@@ -6002,6 +6002,18 @@ growl@1.10.5:
   resolved "https://registry.yarnpkg.com/growl/-/growl-1.10.5.tgz#f2735dc2283674fa67478b10181059355c369e5e"
   integrity sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA==
 
+handlebars@^4.7.7:
+  version "4.7.7"
+  resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.7.tgz#9ce33416aad02dbd6c8fafa8240d5d98004945a1"
+  integrity sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==
+  dependencies:
+    minimist "^1.2.5"
+    neo-async "^2.6.0"
+    source-map "^0.6.1"
+    wordwrap "^1.0.0"
+  optionalDependencies:
+    uglify-js "^3.1.4"
+
 har-schema@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/har-schema/-/har-schema-2.0.0.tgz#a94c2224ebcac04782a0d9035521f24735b7ec92"
@@ -7980,6 +7992,11 @@ negotiator@0.6.3:
   resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.3.tgz#58e323a72fedc0d6f9cd4d31fe49f51479590ccd"
   integrity sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==
 
+neo-async@^2.6.0:
+  version "2.6.2"
+  resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f"
+  integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==
+
 next-tick@^1.1.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/next-tick/-/next-tick-1.1.0.tgz#1836ee30ad56d67ef281b22bd199f709449b35eb"
@@ -9745,11 +9762,24 @@ solidity-ast@^0.4.15:
   resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.32.tgz#ba613ca24c7c79007798033e8a0f32a71285f09e"
   integrity sha512-vCx17410X+NMnpLVyg6ix4NMCHFIkvWrJb1rPBBeQYEQChX93Zgb9WB9NaIY4zpsr3Q8IvAfohw+jmuBzGf8OQ==
 
+solidity-ast@^0.4.38:
+  version "0.4.46"
+  resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.46.tgz#d0745172dced937741d07464043564e35b147c59"
+  integrity sha512-MlPZQfPhjWXqh7YxWcBGDXaPZIfMYCOHYoLEhGDWulNwEPIQQZuB7mA9eP17CU0jY/bGR4avCEUVVpvHtT2gbA==
+
 solidity-comments-extractor@^0.0.7:
   version "0.0.7"
   resolved "https://registry.yarnpkg.com/solidity-comments-extractor/-/solidity-comments-extractor-0.0.7.tgz#99d8f1361438f84019795d928b931f4e5c39ca19"
   integrity sha512-wciNMLg/Irp8OKGrh3S2tfvZiZ0NEyILfcRCXCD4mp7SgK/i9gzLfhY2hY7VMCQJ3kH9UB9BzNdibIVMchzyYw==
 
+solidity-docgen@^0.6.0-beta.35:
+  version "0.6.0-beta.35"
+  resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.35.tgz#174d7fe54efa8b10f7d3cbe0dfc40e52e11bf867"
+  integrity sha512-9QdwK1THk/MWIdq1PEW/6dvtND0pUqpFTsbKwwU9YQIMYuRhH1lek9SsgnsGGYtdJ0VTrXXcVT30q20a8Y610A==
+  dependencies:
+    handlebars "^4.7.7"
+    solidity-ast "^0.4.38"
+
 source-map-resolve@^0.5.0:
   version "0.5.3"
   resolved "https://registry.yarnpkg.com/source-map-resolve/-/source-map-resolve-0.5.3.tgz#190866bece7553e1f8f267a2ee82c606b5509a1a"
@@ -9794,7 +9824,7 @@ source-map@^0.5.6, source-map@^0.5.7:
   resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.5.7.tgz#8a039d2d1021d22d1ea14c80d8ea468ba2ef3fcc"
   integrity sha1-igOdLRAh0i0eoUyA2OpGi6LvP8w=
 
-source-map@^0.6.0:
+source-map@^0.6.0, source-map@^0.6.1:
   version "0.6.1"
   resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263"
   integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==
@@ -10645,6 +10675,11 @@ typical@^5.2.0:
   resolved "https://registry.yarnpkg.com/typical/-/typical-5.2.0.tgz#4daaac4f2b5315460804f0acf6cb69c52bb93066"
   integrity sha512-dvdQgNDNJo+8B2uBQoqdb11eUCE1JQXhvjC/CZtgvZseVd5TYMXnq0+vuUemXbd/Se29cTaUuPX3YIc2xgbvIg==
 
+uglify-js@^3.1.4:
+  version "3.17.4"
+  resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.17.4.tgz#61678cf5fa3f5b7eb789bb345df29afb8257c22c"
+  integrity sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==
+
 ultron@~1.1.0:
   version "1.1.1"
   resolved "https://registry.yarnpkg.com/ultron/-/ultron-1.1.1.tgz#9fe1536a10a664a65266a1e3ccf85fd36302bc9c"
@@ -11477,6 +11512,11 @@ word-wrap@^1.2.3, word-wrap@~1.2.3:
   resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.3.tgz#610636f6b1f703891bd34771ccb17fb93b47079c"
   integrity sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==
 
+wordwrap@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb"
+  integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==
+
 wordwrapjs@^4.0.0:
   version "4.0.1"
   resolved "https://registry.yarnpkg.com/wordwrapjs/-/wordwrapjs-4.0.1.tgz#d9790bccfb110a0fc7836b5ebce0937b37a8b98f"

From 5f22a880b3dd32708453587f503f00a0e54d5a72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?=
 <michalina.cienciala@keep.network>
Date: Wed, 19 Apr 2023 14:33:37 +0200
Subject: [PATCH 02/10] Update name of the secrets

---
 .github/workflows/contracts-ecdsa-docs.yml         | 4 ++--
 .github/workflows/contracts-random-beacon-docs.yml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 8380bd9d10..054c5da583 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -71,5 +71,5 @@ jobs:
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
-      gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }}
-      gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }}
+      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}
+      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index 13110136dc..64b67b4d28 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -71,5 +71,5 @@ jobs:
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
-      gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }}
-      gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }}
+      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}
+      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}

From d6d5145402d9e7164e3291865b2cfc5991b9657f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?=
 <michalina.cienciala@keep.network>
Date: Wed, 19 Apr 2023 14:59:44 +0200
Subject: [PATCH 03/10] Update commiter's e-mail

---
 .github/workflows/contracts-ecdsa-docs.yml         | 2 +-
 .github/workflows/contracts-random-beacon-docs.yml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 054c5da583..df3b3d6150 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -67,7 +67,7 @@ jobs:
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/tbtc-v2/ecdsa-api
       destinationBranch: main
-      userEmail: thesis-valkyrie@users.noreply.github.com
+      userEmail: valkyrie@thesis.co
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index 64b67b4d28..ba80ab32ec 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -67,7 +67,7 @@ jobs:
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/random-beacon/random-beacon-api
       destinationBranch: main
-      userEmail: thesis-valkyrie@users.noreply.github.com
+      userEmail: valkyrie@thesis.co
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}

From 62aaae9fe74680cad7dd96d463aec44da4268439 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?=
 <michalina.cienciala@keep.network>
Date: Tue, 25 Apr 2023 10:27:57 +0200
Subject: [PATCH 04/10] Rename input with project directory

The name of the input in the reusable action has changed, we're updating the
name in the jobs that use it.
---
 .github/workflows/contracts-ecdsa-docs.yml         | 4 ++--
 .github/workflows/contracts-random-beacon-docs.yml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index df3b3d6150..64929a590d 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -44,7 +44,7 @@ jobs:
         || github.event_name == 'workflow_dispatch'
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
-      projectSubfolder: /solidity/ecdsa
+      projectDir: /solidity/ecdsa
       publish: false
       commentPR: true
       exportAsGHArtifacts: true
@@ -61,7 +61,7 @@ jobs:
     if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
-      projectSubfolder: /solidity/ecdsa
+      projectDir: /solidity/ecdsa
       publish: true
       verifyCommits: true
       destinationRepo: threshold-network/threshold
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index ba80ab32ec..f6299d3e60 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -44,7 +44,7 @@ jobs:
         || github.event_name == 'workflow_dispatch'
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
-      projectSubfolder: /solidity/random-beacon
+      projectDir: /solidity/random-beacon
       publish: false
       commentPR: true
       exportAsGHArtifacts: true
@@ -61,7 +61,7 @@ jobs:
     if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
-      projectSubfolder: /solidity/random-beacon
+      projectDir: /solidity/random-beacon
       publish: true
       verifyCommits: true
       destinationRepo: threshold-network/threshold

From daaf3e199eb4f9c2ba2d7587ce9fda6b2c0b8fc6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?=
 <michalina.cienciala@keep.network>
Date: Wed, 3 May 2023 13:47:12 +0200
Subject: [PATCH 05/10] Update destination branch input's name

We decided to push the docs updates not directly to branch synched with GitBook,
but create a PR and set a GitBook-synched branch as a base branch for that PR.
This resulted in changes in the
`keep-network/ci/.github/workflows/reusable-solidity-docs.yml`
workflow's inputs.
---
 .github/workflows/contracts-ecdsa-docs.yml         | 6 +++---
 .github/workflows/contracts-random-beacon-docs.yml | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 64929a590d..d6617950bd 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -53,8 +53,8 @@ jobs:
   # `refs/tags/solidity/`. It will generate contracts documentation in
   # Markdown and sync it with a specific path of
   # `threshold-network/threshold` repository. If changes will be detected,
-  # the destination repository will be updated. The commit pushing the
-  # changes will be verified using GPG key.
+  # a PR updating the docs will be created in the destination repository. The
+  # commit pushing the changes will be verified using GPG key.
   contracts-docs-publish:
     name: Publish contracts documentation
     needs: docs-detect-changes
@@ -66,7 +66,7 @@ jobs:
       verifyCommits: true
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/tbtc-v2/ecdsa-api
-      destinationBranch: main
+      destinationBaseBranch: main
       userEmail: valkyrie@thesis.co
       userName: Valkyrie
     secrets:
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index f6299d3e60..260c340f68 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -53,8 +53,8 @@ jobs:
   # `refs/tags/solidity/`. It will generate contracts documentation in
   # Markdown and sync it with a specific path of
   # `threshold-network/threshold` repository. If changes will be detected,
-  # the destination repository will be updated. The commit pushing the
-  # changes will be verified using GPG key.
+  # a PR updating the docs will be created in the destination repository. The
+  # commit pushing the changes will be verified using GPG key.
   contracts-docs-publish:
     name: Publish contracts documentation
     needs: docs-detect-changes
@@ -66,7 +66,7 @@ jobs:
       verifyCommits: true
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/random-beacon/random-beacon-api
-      destinationBranch: main
+      destinationBaseBranch: main
       userEmail: valkyrie@thesis.co
       userName: Valkyrie
     secrets:

From e55d4629de8cce693439a57315471154f0cae48f Mon Sep 17 00:00:00 2001
From: Michalina <michalina.cienciala@akena.co>
Date: Wed, 21 Jun 2023 14:54:13 +0200
Subject: [PATCH 06/10] Fix values of GPG secrets

---
 .github/workflows/contracts-ecdsa-docs.yml         | 4 ++--
 .github/workflows/contracts-random-beacon-docs.yml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index d6617950bd..5d45417494 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -71,5 +71,5 @@ jobs:
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
-      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}
-      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}
+      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}
+      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index 260c340f68..61bd5a0c08 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -71,5 +71,5 @@ jobs:
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
-      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}
-      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}
+      gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }}
+      gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }}

From 2e04176f79191004fbc1e692178f2b42a7757de8 Mon Sep 17 00:00:00 2001
From: Michalina <michalina.cienciala@akena.co>
Date: Wed, 21 Jun 2023 14:57:07 +0200
Subject: [PATCH 07/10] Change Valkyrie's to noreply email

Change introduced to fix the 'Your push would publish a private email address.'
error.
---
 .github/workflows/contracts-ecdsa-docs.yml         | 2 +-
 .github/workflows/contracts-random-beacon-docs.yml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 5d45417494..3339d12c5d 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -67,7 +67,7 @@ jobs:
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/tbtc-v2/ecdsa-api
       destinationBaseBranch: main
-      userEmail: valkyrie@thesis.co
+      userEmail: 38324465+thesis-valkyrie@users.noreply.github.com
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index 61bd5a0c08..ff7e682e28 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -67,7 +67,7 @@ jobs:
       destinationRepo: threshold-network/threshold
       destinationFolder: ./docs/app-development/random-beacon/random-beacon-api
       destinationBaseBranch: main
-      userEmail: valkyrie@thesis.co
+      userEmail: 38324465+thesis-valkyrie@users.noreply.github.com
       userName: Valkyrie
     secrets:
       githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }}

From c7f233c3d7c104bdad8e143d32627dcdab53c4ce Mon Sep 17 00:00:00 2001
From: Michalina <michalina.cienciala@akena.co>
Date: Tue, 27 Jun 2023 10:02:01 +0200
Subject: [PATCH 08/10] Add temporary config to publish the docs from `main`

The workflow is meant to publish the docs on new releases, but as we already
had releases when workflow wasn't implemented, we need to publish the docs
representing the current state of the API. We are satisfied with docummenting
based on the `main` branch state. After docs get publish, we need to revert this
change.
---
 .github/workflows/contracts-ecdsa-docs.yml         | 3 ++-
 .github/workflows/contracts-random-beacon-docs.yml | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 3339d12c5d..ce2ed8c7bd 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -58,7 +58,8 @@ jobs:
   contracts-docs-publish:
     name: Publish contracts documentation
     needs: docs-detect-changes
-    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
+    # TODO: remove last OR
+    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
       projectDir: /solidity/ecdsa
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index ff7e682e28..f511cee951 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -58,7 +58,8 @@ jobs:
   contracts-docs-publish:
     name: Publish contracts documentation
     needs: docs-detect-changes
-    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
+    # TODO: remove last OR
+    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
       projectDir: /solidity/random-beacon

From 19e2a6ac256a3597ed23914cb6f5aaa284651624 Mon Sep 17 00:00:00 2001
From: Michalina <michalina.cienciala@akena.co>
Date: Tue, 27 Jun 2023 11:07:41 +0200
Subject: [PATCH 09/10] Avoid executing `contracts-docs-publish` parallelly

As triggers for the `Publish contracts documentation` jobs in the workflows
generating Random Beacon and ECDSA API docs are the same (and also the
previously executed steps are very similar, it's likely that the both jobs will
start and the same or very similar time.
When that happens it's very likely that the both jobs will pull the
`auto-update-solidity-api-docs` branch at the same state and one of the jobs
will push a commit with updated docs, while the other won't be able to do that,
as the state of the branch will be different than when the pull happened.
The error we see in that case is following:
```
error: failed to push some refs to 'https://github.com/threshold-network/threshold.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
```
To avoid such situations we add a 4 minutes wait before we execute the 'Publish
contracts documentation' job in ECDSA workflow. This should be more than
enught for the Random Beacon's `Publish contracts documentation` to finish.

There is still a small change that both `Publish contracts documentation` jobs
will run at similar time (if something slows down the execution of the Random
Beacon workflow) and cause a failure of one of them, but in that unlikely
scenario, we can always rerun the failing job and it should pass on that second
run.
---
 .github/workflows/contracts-ecdsa-docs.yml | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index ce2ed8c7bd..7a57721733 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -49,6 +49,19 @@ jobs:
       commentPR: true
       exportAsGHArtifacts: true
 
+  # This job is needed to avoid a clash of `contracts-docs-publish` jobs for
+  # `random-beacon` and `ecdsa` projects (if both are run and pull the code at
+  # the same time and try to push to the same branch, one of them will fail). 
+  contracts-docs-prepublish-wait:
+    name: Wait for contracts docs to be published
+    needs: docs-detect-changes
+     # TODO: remove last OR
+    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Wait 4 minutes
+        run: sleep 240
+
   # This job will be triggered for releases which name starts with
   # `refs/tags/solidity/`. It will generate contracts documentation in
   # Markdown and sync it with a specific path of
@@ -57,9 +70,7 @@ jobs:
   # commit pushing the changes will be verified using GPG key.
   contracts-docs-publish:
     name: Publish contracts documentation
-    needs: docs-detect-changes
-    # TODO: remove last OR
-    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
+    needs: contracts-docs-prepublish-wait
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
       projectDir: /solidity/ecdsa

From 0a1cf1915a1ee64bc2c499ab9a888b97094b9b71 Mon Sep 17 00:00:00 2001
From: Michalina <michalina.cienciala@akena.co>
Date: Tue, 27 Jun 2023 12:34:08 +0200
Subject: [PATCH 10/10] Remove testing config

---
 .github/workflows/contracts-ecdsa-docs.yml         | 3 +--
 .github/workflows/contracts-random-beacon-docs.yml | 3 +--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/contracts-ecdsa-docs.yml b/.github/workflows/contracts-ecdsa-docs.yml
index 7a57721733..97f182690d 100644
--- a/.github/workflows/contracts-ecdsa-docs.yml
+++ b/.github/workflows/contracts-ecdsa-docs.yml
@@ -55,8 +55,7 @@ jobs:
   contracts-docs-prepublish-wait:
     name: Wait for contracts docs to be published
     needs: docs-detect-changes
-     # TODO: remove last OR
-    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
+    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
     runs-on: ubuntu-latest
     steps:
       - name: Wait 4 minutes
diff --git a/.github/workflows/contracts-random-beacon-docs.yml b/.github/workflows/contracts-random-beacon-docs.yml
index f511cee951..ff7e682e28 100644
--- a/.github/workflows/contracts-random-beacon-docs.yml
+++ b/.github/workflows/contracts-random-beacon-docs.yml
@@ -58,8 +58,7 @@ jobs:
   contracts-docs-publish:
     name: Publish contracts documentation
     needs: docs-detect-changes
-    # TODO: remove last OR
-    if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/3534/merge'
+    if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
     uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main
     with:
       projectDir: /solidity/random-beacon