docs: document deployment functions

.pre-commit-config.yaml

@@ -41,4 +41,4 @@ repos:
         name: Project Unit Tests
         entry: npm run test
         language: system
-        types: [solidity, javascript]
+        types: [solidity, ts]

scripts/deployment-utils/deploy-proxy.ts

@@ -86,6 +86,16 @@ function getInitParameters(
   }
 }
 
+/**
+ * This function deploys the LiquidityBridgeContract proxy and initializes it. This includes deploying
+ * the required libraries and linking them to the contract. The parameter values vary depending on the
+ * network and can be checked at {@link getInitParameters}.
+ *
+ * @param network The network to deploy the contract to.
+ * @param opts Options object, currently only has a verbose flag.
+ *
+ * @returns The address of the deployed proxy.
+ */
 export async function deployLbcProxy(
   network: string,
   opts = { verbose: true }

scripts/deployment-utils/deploy.ts

@@ -1,11 +1,24 @@
 import { readFileSync, writeFileSync } from "fs";
 
+/**
+ * Layout of the addresses.json file. Consist of a map of networks, each network has a map of
+ * contracts and the value of that contract has the structure defined in {@link DeployedContractInfo}.
+ */
 export interface DeploymentConfig {
   [network: string]: {
     [contract: string]: DeployedContractInfo;
   };
 }
 
+/**
+ * This interface holds the information of a deployed contract in the addresses.json file.
+ *
+ * @param deployed - Indicates if the contract has been deployed or not, if the contract is
+ * in the file it usually means it was already deployed. But this value can be set to false
+ * to execute a re deployment.
+ *
+ * @param address - The address of the deployed contract.
+ */
 export interface DeployedContractInfo {
   deployed: boolean;
   address?: string;
@@ -22,10 +35,17 @@ export const LOCAL_NETWORK = "rskRegtest";
 const UNIT_TEST_NETWORK = "hardhat";
 
 const testConfig: DeploymentConfig = { [UNIT_TEST_NETWORK]: {} };
+
+/**
+ * Reads the addresses.json file and returns its content as a {@link DeploymentConfig} object.
+ *
+ * @returns { DeploymentConfig } The content of the addresses.json file.
+ */
 export const read: () => DeploymentConfig = () =>
   Object.keys(testConfig[UNIT_TEST_NETWORK]).length > 0
     ? testConfig
     : JSON.parse(readFileSync(ADDRESSES_FILE).toString());
+
 const write = (newConfig: DeploymentConfig) => {
   const oldConfig = read();
   writeFileSync(
@@ -34,6 +54,17 @@ const write = (newConfig: DeploymentConfig) => {
   );
 };
 
+/**
+ * Is the function that deploys a contract and updates the addresses.json file. Every deployment
+ * should call this function at some point in order to save the addresses. If the contract figures
+ * as deployed in the addresses.json file, it will not be deployed again.
+ *
+ * @param name The name of the contract to deploy as it should appear in the addresses.json file.
+ * @param network The name of the network to deploy the contract to as it appears in the addresses.json file.
+ * @param act The deployment function itself, this function should return the address of the deployed contract.
+ *
+ * @returns { Promise<DeployedContractInfo> } The information of the deployed contract.
+ */
 export const deploy: deployFunction = async (
   name: string,
   network: string,

scripts/deployment-utils/upgrade-proxy.ts

@@ -36,6 +36,15 @@ async function deployUpgradeLibraries(
   };
 }
 
+/**
+ * This function upgrades the LiquidityBridgeContract proxy contract to the LiquidityBridgeContractV2 version.
+ * it upgrades the proxy whose address is under the key "LiquidityBridgeContract" in the addresses.json file.
+ * It will also deploy and link the required libraries.
+ *
+ * @param network The network to deploy the contract to.
+ * @param opts Options object, currently only has a verbose flag.
+ *
+ */
 export async function upgradeLbcProxy(
   network: string,
   opts = { verbose: true }

scripts/deployment-utils/utils.ts

@@ -5,6 +5,14 @@ export const TEST_NETWORKS = ["localhost", "hardhat", "ganache", LOCAL_NETWORK];
 
 export const REMOTE_NETWORKS = ["rskDevelopment", "rskTestnet", "rskMainnet"];
 
+/**
+ * This function wraps the {@link deploy} function to deploy a contract using ethers.js
+ * and save the results in the addresses.json file.
+ *
+ * @param contract The name of the contract to deploy, as it appears in the addresses.json file.
+ * @param network The name of the network as it appears in the addresses.json file.
+ * @returns { Required<DeployedContractInfo> } The information of the deployed contract.
+ */
 export async function deployContract(
   contract: string,
   network: string