# NFA - Contracts

## Folder Structure

Inside contracts you are going to find:
- [contracts](./contracts): all the developed contracts
- [deployments](./deployments): resultant ABI and info for deployments (each network will have a nested folder)
- [lib](./lib): external modules used by Foundry
- [scripts](./scripts): any utility scripts used for interacting with deployed contracts
- [test](./test): tests suits to validate contracts

And after running it locally some folders may be generated:

- `artifacts`: ABIs and build info generated by Hardhat
- `cache`: cache info used by Hardhat
- `forge-cache`: cache info used by Foundry
- `node_modules`: all dependencies for the Node.js environment
- `out`: resultant ABIs for all contracts that has interactions

## Building

The contracts present in this project are based in [Solidity](https://github.com/ethereum/solidity) and it uses [Node.js](https://nodejs.org/) for running scripts and [yarn](https://yarnpkg.com/) to keep dependencies management.

> ⚠️ Before starting developing make sure you Solidity, Node.js and yarn correctly installed in your environment

Also, make sure you run `yarn` at the root directory to get some required tools.  The rest of these steps assume you are in the [contracts folder](./).

Follow the steps:

1. Clone the repo, [check out how here](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).

2. Install dependencies:

   ```bash
   $ yarn
   ```

3. Compile the contracts to make sure everything is correct:

   ```bash
   $ yarn compile
   ```

   The output should looks like:

   ```bash
   yarn run v1.22.19
   $ hardhat compile
   Compiled 14 Solidity files successfully.
   Done in 0.98s.
   ```

4. Now you are able to make your code changes in the project. To help with Solidity, check [the language references](https://docs.soliditylang.org/).

## ✅ Testing

The project is covered with test suits (Foundry & Hardhat) that must pass to guarantee code integrity.

### HardHat Tests

All HardHat tests are located at [this directory](./test).

1.  Make sure that you have the dependencies installed:

    ```
    $ yarn
    ```

2.  Run:

    ```
    $ yarn test:hardhat
    ```

    The output should finish looking like:

    ```
    ...

    33 passing (1s)

    Done in 2.11s.
    ```

### Foundry tests

All Forge tests are located at [this directory](./test/foundry).

In order to run them, you need to have Forge by Foundry installed on your machine (check [this](https://book.getfoundry.sh/getting-started/installation.html) installation guide).

It is also required for you to have [forge-std](https://github.com/foundry-rs/forge-std/tree/cd7d533f9a0ee0ec02ad81e0a8f262bc4203c653) in your `./lib/` directory. In case you don't have it yet, you can run:

```
$ git submodule update --init --recursive
```

After installing Foundry and its components, you can simply run in the root directory:

```
$ yarn test:foundry
```

It is going to execute all test cases that are described in the [test/foundry](./test/foundry/) directory. Your output should looks like:

```
Test result: ok. 36 passed; 0 failed; finished in 4.06ms
Done in 0.58s.
```

## Running Both Test Environments

Alternatively, you can run both test environments by executing:

```
$ yarn test
```

> ⚠️ Please make sure to update tests as appropriate before pushing code

## 🚀 Deployment

This guide contains instructions to deploy the contract on three networks. If the execution is successful, you will see the contract address on your screen at the end of the instructions.

### **Hardhat Local Network**

HardHat offers a local testnet environment that allows users and testers to deploy and interact with contracts without the need to contact external APIs and endpoints.

To start your local HardHat network, you need to run a node first. It is important to not terminate the command before proceeding with the instructions:

```
$ yarn node:hardhat
```

To deploy the contract on the HardHat network, execute:

```
$ yarn deploy:hardhat
```

If the execution is successful, you will see the contract address on your screen.

### **Polygon Mumbai Testnet**

To deploy the contract on the testnet, you have to first export your wallet's private key and update the `.env.example` file at the root directory of this repository.

The [.env.example](./.env.example) file needs to be renamed to `.env` before continuing. Make sure you are using your private API URL, if you have one.

After updating the `.env` file, you can run:

```
$ yarn deploy:mumbai
```

to deploy the contract on the testnet. Please note that your wallet needs to hold enough Mumbai MATIC for the deployment to be successful. To reach more in-depth information about how to deploy contract checkout [this guide](https://wiki.polygon.technology/docs/develop/alchemy).

<!-- TODO: add this section after the mainnet setup is done and tested
**Polygon main-net**

To deploy the contract on the testnet, you have to first export your wallet's private key and update the `.env.example` file at the root directory of this repository.

The [.env.example](./.env.example) file needs to be renamed to `.env` before continuing. Make sure you are using your private API URL, if you have one.

After updating the `.env` file, you can run:

```
yarn deploy:mainnet
```

to deploy the contract on the testnet. Please note that your wallet needs to hold enough Mumbai MATIC for the deployment to be successful.
-->

## ▶️ Interaction scripts

Right away, in the [scripts](./scripts/) folder you are able to see some scripts that will help you to interact with deployed contracts. By default you are able to select `localhost`, `hardhat` or `mumbai` network name predefined on [hardhat.config.ts](./hardhat.config.ts). The scripts will be using the deployment information stored in the [deployments](./deployments/) folder. You should have a nested folder for each of the networks you have deployed it. The scripts needs be run using the Hardhat environment following the pattern:

```bash
# Replace <script_name> with the selected script
# Replace <network_name> with the selected network
$ npx hardhat run scripts/<script_name>.js --network <network_name>
```

> 💡You are able to see and change the arguments for each script at the top of each file

<!-- TODO: add the commands here when they are done
### Admin commands

The project should provide a way for interacting with the contract as owner with CLI.

> 🛠️ Work in progress...

-->