diff --git a/TEST_SETUP.md b/TEST_SETUP.md index a15e18b83..cdc7ede30 100644 --- a/TEST_SETUP.md +++ b/TEST_SETUP.md @@ -10,7 +10,7 @@ - [Hedera accounts](https://docs.hedera.com/hedera/getting-started/introduction#create-hedera-portal-profile-faucet) - [prettier pluggin](https://prettier.io/) (recommended) -**_Notes_**: If your IDE does not support the Prettier plugin, please follow the [code formatter guidelines](GUIDELINES.md#code-formatter) to maintain the consistent code format. +**_Notes_**: If your IDE does not support the Prettier plugin, please follow the [code formatter guidelines](TEST_SETUP.md#code-formatter) to maintain the consistent code format. ## Building and Running the Project @@ -80,4 +80,3 @@ Before committing your new changes, please run command below to format all files ``` **_Notes_**: This is applicable only in cases where you haven't configured prettier within your IDE. - diff --git a/system-contract-dapp-playground/README.md b/system-contract-dapp-playground/README.md index e32cbb5fc..21ad5e324 100644 --- a/system-contract-dapp-playground/README.md +++ b/system-contract-dapp-playground/README.md @@ -7,7 +7,7 @@ ## Overview -TBD +An intuitive low-code playground that eliminates the complexities, reduces learning curves, and allows developers to effortlessly interact with the Hedera’s powerful system contracts. ## Getting started @@ -143,13 +143,3 @@ Congratulations! You are now ready to execute the project! ``` **_important_**: must [build the project](README.md#building-the-project) first. - -## Config - -| Config files | Purpose | -| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [next-env.d.ts](next-env.d.ts) | a declaration file that allows to extend the global TypeScript types and declare custom types specific to Next.js project. This file ensures that TypeScript correctly recognizes Next.js-specific types and prevents type-checking errors. | -| [next.config.js](next.config.js) | allows to customize the Next.js configuration, including settings for features, plugins, environment variables, and webpack behavior. | -| [postcss.config.js](postcss.config.js) | specifies the PostCSS plugins and their settings used to process and transform CSS code during the build process. | -| [tailwind.config.js](tailwind.config.js) | allows to customize Tailwind CSS by providing options to modify colors, fonts, breakpoints, variants, and more, tailoring the framework to specific project requirements. | -| [tsconfig.json](tsconfig.json) | configures the TypeScript compiler settings, enabling to specify target environments, module systems, and other options, ensuring type-checking and compilation of TypeScript code for the project. | diff --git a/system-contract-dapp-playground/docs/source-code-document/README.md b/system-contract-dapp-playground/docs/source-code-document/README.md new file mode 100644 index 000000000..b2aa20747 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/README.md @@ -0,0 +1,79 @@ +# Source code documentation + +## Overview + +The `System Contract DApp Playground` project, often referred to as the DApp or DApp Playground, has been developed using a stack comprising the `React library`, `Next.js framework`, `Tailwind CSS`, and the `Chakra UI component library`. The primary objective behind this project is to provide developers with a seamless and user-friendly platform for interacting with Hedera's system contracts. The project's core purpose is to simplify the process, minimize complexities, shorten learning curves, and ultimately save valuable time for developers. + +## Purpose + +This document is intended to offer a thorough and elucidating account of the code components encompassed within the DApp, facilitating a deeper understanding of its inner workings. + +## Goals + +Offers a concise and accessible overview of the code components as well as provides a clear understanding of the codebase. This serves as a valuable resource for individuals interested in contributing to the project, enabling them to quickly grasp its structure and functionalities. + +### Table of contents + +##### Codebase Structure + +- [Folder tree](./codebase-structure/1.folder-tree/index.md) + +- Codebase Walkthrough + + - [\_\_tests\_\_/](./codebase-structure/2.codebase-walkthrough/__tests__/index.md) + - [prerequisite-check/](./codebase-structure/2.codebase-walkthrough/prerequisite-check/index.md) + - [public/](./codebase-structure/2.codebase-walkthrough/public/index.md) + - src/ + + - [api/](./codebase-structure/2.codebase-walkthrough/src/api/index.md) + - [app/](./codebase-structure/2.codebase-walkthrough/src/app/index.md) + - components/ + + - [activity/](./codebase-structure/2.codebase-walkthrough/src/components/activity/index.md) + - [background-gradients/](./codebase-structure/2.codebase-walkthrough/src/components/background-gradients/index.md) + - [common/](./codebase-structure/2.codebase-walkthrough/src/components/common/index.md) + - [contract-interactions/](./codebase-structure/2.codebase-walkthrough/src/components/contract-interactions/index.md) + - [footer/](./codebase-structure/2.codebase-walkthrough/src/components/footer/index.md) + - [navbar/](./codebase-structure/2.codebase-walkthrough/src/components/navbar/index.md) + - [sidebar/](./codebase-structure/2.codebase-walkthrough/src/components/sidebar/index.md) + - [toast/](./codebase-structure/2.codebase-walkthrough/src/components/toast/index.md) + - [wallet-popup/](./codebase-structure/2.codebase-walkthrough/src/components/wallet-popup/index.md) + + - [fonts/](./codebase-structure/2.codebase-walkthrough/src/fonts/index.md) + - [hooks/](./codebase-structure/2.codebase-walkthrough/src/hooks/index.md) + - [libs/](./codebase-structure/2.codebase-walkthrough/src/libs/index.md) + - [sections/](./codebase-structure/2.codebase-walkthrough/src/sections/index.md) + - [styles/](./codebase-structure/2.codebase-walkthrough/src/styles/index.md) + - [types/](./codebase-structure/2.codebase-walkthrough/src/types/index.md) + - [utils/](./codebase-structure/2.codebase-walkthrough/src/utils/index.md) + - [middleware.ts/](./codebase-structure/2.codebase-walkthrough/src/middleware.md) + + - [config-files](./codebase-structure/2.codebase-walkthrough/config-files/index.md) + +#### Tutorials on How to Add a New System Contract to the DApp + +Here is a step-by-step guide for adding a new contract to the DApp: + +1. **Prerequisite Check** + + Begin by ensuring that the contract assets are available in the `prerequisite-check` directory. Follow the tutorial [here](./codebase-structure/2.codebase-walkthrough/prerequisite-check/index.md#b-adding-new-system-contracts-to-the-dapp) for detailed instructions. + +2. **New Dedicated Route** + + Create a dedicated route for the new system contract. Learn how to do this by following the guide [here](./codebase-structure/2.codebase-walkthrough/src/app/index.md#b-adding-new-system-contracts-to-the-dapp). + +3. **Add the Dedicated Route to `PROTECTED_ROUTES`** + + As the new route is considered a protected route, you need to add it to the `PROTECTED_ROUTES` constant variable. Find out how to do this [here](./codebase-structure/2.codebase-walkthrough/src/middleware.md#adding-new-system-contracts-to-the-dapp). + +4. **Contract Section UI Component** + + Create a client-side section-level UI component to showcase the new contract. Follow the instructions provided [here](./codebase-structure/2.codebase-walkthrough/src/sections/index.md#b-adding-new-system-contracts-to-the-dapp). + +5. **Method APIs** + + Implement the method APIs for the new system contract. Learn how to add these APIs [here](./codebase-structure/2.codebase-walkthrough/src/api/index.md#b-adding-new-system-contracts-to-the-dapp). + +6. **Contract-Interaction UI Component** + + Design the contract-interaction UI component that allows users to interact with the smart contract. Note that this component's layout may vary depending on the specific method APIs. Detailed instructions can be found [here](./codebase-structure/2.codebase-walkthrough/src/components/contract-interactions/index.md#b-adding-new-system-contracts-to-the-dapp). diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/1.folder-tree/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/1.folder-tree/index.md new file mode 100644 index 000000000..2cb1e223a --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/1.folder-tree/index.md @@ -0,0 +1,196 @@ +# Source code documentation + +## Codebase structure (folder tree) + + . + ├── __tests__/ + │ ├──ethers/ + │ ├──hedera/ + │ │ ├── erc20-interactions/ + │ │ ├── erc721-interactions/ + │ │ ├── exchange-rate-interactions/ + │ │ ├── helper/ + │ │ ├── ihrc-interactions + │ │ ├── prng-interactions + │ │ └── hts-interactions/ + │ │ └── token-create-custom/ + │ │ └── token-management-contract/ + │ │ └── token-transfer-contract/ + │ │ └── token-query-contract/ + │ ├──mirror-node/ + │ │ └── erc20-interactions/ + │ └──utils/ + │ └── common/ + │ + ├── prerequisite-check/ + │ └──contracts-info/ + │ └──scripts/ + │ + ├── docs/ + │ + ├── public/ + │ ├── assets + │ │ └── docs/ + │ │ └── icons/ + │ │ └── socials/ + │ └── brandings/ + │ + ├── src/ + │ ├── api/ + │ │ ├── cookies/ + │ │ ├── ethers/ + │ │ ├── localStorage/ + │ │ ├── mirror-node/ + │ │ ├── wallet/ + │ │ └─ hedera/ + │ │ ├── erc20-interactions/ + │ │ ├── erc721-interactions/ + │ │ ├── exchange-rate-interactions/ + │ │ ├── ihrc-interactions/ + │ │ ├── prng-interactions/ + │ │ └── hts-interactions/ + │ │ └── tokenCreateCustom-interactions/ + │ │ └── tokenManagement-interactions/ + │ │ └── tokenQuery-interactions/ + │ │ └── tokenTransfer-interactions/ + │ ├── app/ + │ │ ├── activity/ + │ │ └── hedera/ + │ │ └── erc-20/ + │ │ └── erc-721/ + │ │ └── exchange-rate-hip-475/ + │ │ └── hrc-719/ + │ │ └── hts-hip-206/ + │ │ └── overview/ + │ │ └── prng-hip-351/ + │ │ + │ ├── component/ + │ │ ├── background-gradients/ + │ │ ├── common/ + │ │ │ └── components/ + │ │ │ └── methods/ + │ │ ├── contract-interaction/ + │ │ │ ├── erc/ + │ │ │ │ ├── deployment/ + │ │ │ │ ├── erc-20/ + │ │ │ │ │ ├── methods/ + │ │ │ │ │ │ └── balance-of/ + │ │ │ │ │ │ └── mint/ + │ │ │ │ │ │ └── token-information/ + │ │ │ │ │ │ └── token-permission/ + │ │ │ │ │ │ └── token-transfer/ + │ │ │ │ └── erc-721/ + │ │ │ │ └── methods/ + │ │ │ │ └── approve/ + │ │ │ │ └── balance-of/ + │ │ │ │ └── mint/ + │ │ │ │ └── operator-approve/ + │ │ │ │ └── owner-of/ + │ │ │ │ └── token-information/ + │ │ │ │ └── token-transfer/ + │ │ │ │ └── token-uri/ + │ │ │ │ + │ │ │ ├── exchange-rate/ + │ │ │ │ ├── deployment/ + │ │ │ │ └── methods/ + │ │ │ │ + │ │ │ ├── hts/ + │ │ │ │ ├── shared/ + │ │ │ │ │ └── components/ + │ │ │ │ │ └── methods/ + │ │ │ │ │ └── states/ + │ │ │ │ │ + │ │ │ │ ├── token-create-custom/ + │ │ │ │ │ └── methods/ + │ │ │ │ │ └── AssociateHederaToken/ + │ │ │ │ │ └── FungibleTokenCreate/ + │ │ │ │ │ └── GrantTokenKYC/ + │ │ │ │ │ └── MintHederaToken/ + │ │ │ │ │ └── NonFungibleTokenCreate/ + │ │ │ │ │ + │ │ │ │ ├── token-management-contract/ + │ │ │ │ │ └── methods/ + │ │ │ │ │ └── manageTokenDelete/ + │ │ │ │ │ └── manageTokenInfo/ + │ │ │ │ │ └── manageTokenPermission/ + │ │ │ │ │ └── manageTokenRelation/ + │ │ │ │ │ └── manageTokenStatus/ + │ │ │ │ │ └── manageTokenSupplyReduction/ + │ │ │ │ │ + │ │ │ │ ├── token-query-contract/ + │ │ │ │ │ └── methods/ + │ │ │ │ │ └── querySpecificToken/ + │ │ │ │ │ └── queryTokenGeneralInfo/ + │ │ │ │ │ └── queryTokenPermission/ + │ │ │ │ │ └── queryTokenStatus/ + │ │ │ │ │ └── queryTokenValidity/ + │ │ │ │ │ + │ │ │ │ └── token-transfer-contract + │ │ │ │ └── methods/ + │ │ │ │ └── transferCrypto/ + │ │ │ │ └── transferMultipleTokens/ + │ │ │ │ └── transferSingleToken/ + │ │ │ │ + │ │ │ ├── ihrc/ + │ │ │ │ └── methods/ + │ │ │ │ + │ │ │ └── prng/ + │ │ │ └── methods/ + │ │ │ + │ │ ├── footer/ + │ │ │ + │ │ ├── navbar/ + │ │ │ + │ │ ├── sidebar/ + │ │ │ + │ │ └── toast/ + │ │ + │ ├── fonts/ + │ │ + │ ├── hooks/ + │ │ + │ ├── libs/ + │ │ ├── chakra/ + │ │ └── framer-motion/ + │ │ + │ ├── sections/ + │ │ ├── activity/ + │ │ ├── erc-20/ + │ │ ├── erc-721/ + │ │ ├── exchange-rate-hip-475/ + │ │ ├── hrc-719/ + │ │ ├── hts-hip-206/ + │ │ ├── landing/ + │ │ ├── overview/ + │ │ └── prng-hip-351/ + │ │ + │ ├── styles/ + │ │ + │ ├── types/ + │ │ ├── common/ + │ │ └── contract-interactions/ + │ │ ├── erc/ + │ │ ├── HTS/ + │ │ └── shared/ + │ │ + │ ├── utils/ + │ │ ├── common/ + │ │ └── contract-interactions/ + │ │ ├── erc/ + │ │ └── HTS/ + │ └── middleware.ts + │ + │ + ├── .eslintrc.json + ├── .gitignore + ├── .prettierrc + ├── jest.config.mjs + ├── Makefile + ├── next-env.d.ts + ├── next.config.js + ├── package-lock.json + ├── package.json + ├── postcss.config.js + ├── README.md + ├── tailwind.config.js + └── tsconfig diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/__tests__/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/__tests__/index.md new file mode 100644 index 000000000..4286cc1fa --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/__tests__/index.md @@ -0,0 +1,81 @@ +# Source code documentation + +## Codebase Walkthrough - **\_\_tests\_\_** folder + +### a. Overview + +The DApp employs the Jest testing framework, with its unit tests organized within the `__tests__/` directory. + +**_Note_**: It's important to note that the structure of the `__tests__/` folder is designed to closely resemble that of the `src/api/` folder, with the exception of certain API folders that are primarily focused on client-browser interactions. + +Here is a breakdown of the **\_\_tests\_\_** folders: + +- `ethers/` folder: Contains unit tests for functionalities connected to the `ethers.js` library. This includes tasks such as contract deployment, the generation of `ethers.Contract` instances, and related operations. + +- `hedera/` folder: Comprises unit tests that pertain to interactions with Hedera System Contracts. It covers a range of tests related to these contract interactions. + +- `mirror-node/` folder: Encompasses unit tests related to the utilization of Restful APIs for communicating with Hedera's mirror nodes. + +### b. Adding New Unit Tests + +#### b1. Convention + +- **Folder Structure**: Ensure that any newly added unit tests are placed in the correct folders. Whenever feasible, aim to align the structure of these tests with that of the `src/api/` folder. +- **API-Specific Folders**: Each API should possess its dedicated folder. Additionally, to maintain uniformity and alignment with the `jest` testing framework's naming conventions, the primary index file of each folder should be named `index.test.ts`. + +#### b2. Mocking + +Based on the different type of APIs, different mocking strategies are employed. + +- **Restul APIs**: This project uses `axios` library to make restful APIs, so the unit test should mock the `Axios adapter` using `MockAdapter` from `axios-mock-adapter` library. + +Below is an example showcasing how to achieve this: + +```typescript + const RestMock = new MockAdapter(axios); + const expectedUrl = `https:...` + const mockResponse = {...} + RestMock.onGet(expectedUrl).reply(200, mockResponse) +``` + +- **Mocking External Libraries**: In the context of testing external libraries, the `jest` framework's `.mock` property is utilized. This feature enables the mock implementation of entire library modules, allowing for the assignment of predefined mock values to necessary methods. + +Here's an example demonstrating the mock implementation of the `ethers.Contract` constructor within the project: + +```typescript +// Mock the ethers.Contract constructor +jest.mock('ethers', () => { + const actualEthers = jest.requireActual('ethers'); + return { + ...actualEthers, + Contract: jest.fn().mockImplementation(() => ({ + name: jest.fn().mockResolvedValue('Hedera'), + })), + }; +}); +``` + +- **Contract Interaction**: A fundamental functionality of the DApp involves interactions with smart contracts deployed on the blockchain. Therefore, in all unit tests within the `__tests__/hedera/` directory, you will encounter the mocking of a `baseContract` instance, which serves as a representation of the deployed contracts. + +Below is a basic example of how a `baseContract` instance is mocked for an ERC20 contract: + +```typescript +const expectedName = 'Onasium'; +const expectedSymbol = 'ONAS'; +const expectedDecimals = '8'; +const expectedTotalSupply = '50000000000'; + +// Mocked baseContract object +const baseContract = { + name: jest.fn().mockResolvedValue(expectedName), + symbol: jest.fn().mockResolvedValue(expectedSymbol), + totalSupply: jest.fn().mockResolvedValue(expectedTotalSupply), + decimals: jest.fn().mockResolvedValue(expectedDecimals), +}; +``` + +#### b3. Unit Testing Guidelines + +- **Grouping Related Tests**: Unit tests that share a specific focus, such as testing a particular method, should be logically grouped within a `describe` block. This organizational approach enhances test readability and maintainability. + +- **Comprehensive Testing**: Each unit test should comprehensively evaluate the targeted feature. This includes testing both successful execution cases and failure scenarios. This ensures thorough coverage and robustness in testing the code's behavior. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/config-files/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/config-files/index.md new file mode 100644 index 000000000..75b5e3297 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/config-files/index.md @@ -0,0 +1,15 @@ +# Source code documentation + +## Codebase Walkthrough - **config** files + +| Config files | Purpose | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [.eslintrc.json](.eslintrc.json) | provides ESLint with the necessary configuration to enforce coding styles and best practices, specifically for a Next.js project with a focus on core web vitals. | +| [.prettierrc](.prettierrc) | allows to customize the formatting rules to match the preferred coding style. | +| [jest.config.mjs](jest.config.mjs) | allows to customize the behavior of Jest for the dapp, such as specifying test environments, configuring module resolution, and setting up code transformers. | +| [Makefile](Makefile) | a text file that contains a set of rules and instructions for the make utility, which is a tool used to manage and maintain computer programs. | +| [next-env.d.ts](next-env.d.ts) | a declaration file that allows to extend the global TypeScript types and declare custom types specific to Next.js project. This file ensures that TypeScript correctly recognizes Next.js-specific types and prevents type-checking errors. | +| [next.config.js](next.config.js) | allows to customize the Next.js configuration, including settings for features, plugins, environment variables, and webpack behavior. | +| [postcss.config.js](postcss.config.js) | specifies the PostCSS plugins and their settings used to process and transform CSS code during the build process. | +| [tailwind.config.js](tailwind.config.js) | allows to customize Tailwind CSS by providing options to modify colors, fonts, breakpoints, variants, and more, tailoring the framework to specific project requirements. | +| [tsconfig.json](tsconfig.json) | configures the TypeScript compiler settings, enabling to specify target environments, module systems, and other options, ensuring type-checking and compilation of TypeScript code for the project. | diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/prerequisite-check/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/prerequisite-check/index.md new file mode 100644 index 000000000..a04bd7dfa --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/prerequisite-check/index.md @@ -0,0 +1,35 @@ +# Source code documentation + +## Codebase Walkthrough - **prerequisite-check** folder + +### a. Overview + +Within the DApp, several smart contracts sourced from the primary `hashgraph/hedera-smart-contracts` repository are utilized. The DApp primarily depends on the presence of smart contract metadata to access bytecode for deployment and ABI for decoding information. Hence, it is crucial to ensure that the requisite smart contracts are accessible within the root folder. + +Here is a breakdown of the **prerequisite-check** folder: + +- `contracts-info/` folder: Within this directory, you will find a simple function called `getHederaSmartContractAssets`. Its purpose is to accept the `HederaSmartContractsRootPath` variable as input and subsequently return an object containing all the essential `contract assets` information necessary to validate the presence of the required contracts. + +- `scripts/` folder: Inside this directory, there is a self-executing function responsible for executing the validity-check logic for the smart contracts. Its primary objective is to confirm the availability of both the contract and artifact files at their designated locations. + +### b. Adding New System Contracts to the DApp + +#### b1. Contract Assets + +When adding new system contracts to the DApp, the first crucial step is to include the corresponding `contract assets` object within the returned value of the `getHederaSmartContractAssets` function. You can find this function in the [contracts-info/index.ts](../../../../../../prerequisite-check/contracts-info/index.ts) file. + +For example, consider a `contract assets` object corresponding to `TokenCreateCustomContract`, structured as follows: + +```typescript +{ + name: 'TokenCreateCustomContract', + contractPath: `${HederaSmartContractsRootPath}/contracts/hts-precompile/examples/token-create/TokenCreateCustom.sol`, + artifactPath: `${HederaSmartContractsRootPath}/artifacts/contracts/hts-precompile/examples/token-create/TokenCreateCustom.sol/TokenCreateCustomContract.json`, +} +``` + +In this context, `name` signifies the contract's name, `contractPath` indicates the precise path to the contract's location, and `artifactPath` points to the exact path where the contract's metadata file is stored. + +#### b2. Prerequisite-Check Script + +Within the script, a minor modification is required in the `contractNames` array. Simply include the new `name` from the `contract assets` object mentioned in step **b1. Contract Assets** to the `contractNames` array. The script is specifically designed to evaluate contract assets using their contract names, offering a highly convenient approach. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/public/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/public/index.md new file mode 100644 index 000000000..9b5822aac --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/public/index.md @@ -0,0 +1,5 @@ +# Source code documentation + +## Codebase Walkthrough - **public** folder + +The main purpose of the public folder is to provide a location for files that should be accessible directly by the browser, without going through the module system or being bundled with the rest of the application code. This folder primarily contains image assets that are integral to the user interface and overall user experience of the DApp. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/api/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/api/index.md new file mode 100644 index 000000000..406ac9f88 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/api/index.md @@ -0,0 +1,67 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/api/** Folder + +### a. Overview + +The **src/api/** folder encompasses various subdirectories, each dedicated to a specific category of APIs essential for the DApp's operation. These subdirectories are meticulously organized to streamline the development process and enhance code maintainability. + +Here is a breakdown of the **src/api/** subdirectories: + +- `cookies/` folder: This directory contains APIs and functionalities related to interacting with browser cookies, facilitating data management and persistence. + +- `ethers/` folder: This subdirectory contains APIs and utilities for interacting with the `ethers.js` library, ensuring efficient communication with the `Hedera` network. + +- `hedera/` folder: This directory hosts a set of APIs that are responsible for interacting with Hedera's system contracts. These contracts play a pivotal role in the DApp's functionality. + + - `erc20-interactions/` folder: Contains APIs designed for interacting with the `ERC20Mock` contract, offering features related to ERC-20 token management. + + - `erc721-interactions/` folder: This subdirectory encompasses APIs specialized in interacting with the `ERC721Mock` contract, facilitating operations involving ERC-721 tokens. + + - `exchange-rate-interactions/` folder: Within this directory, you'll find APIs tailored for interacting with the `ExchangeRatePrecompile` contract, enabling the DApp to access exchange rate-related data. + + - `hts-interactions/` folder: Contains APIs that interact with four distinct example contracts representing the HTS (Hedera Token Service) precompile contract. These include `TokenCreateCustomContract`, `TokenManagementContract`, `TokenQueryContract`, and `TokenTransferContract`. + + - `ihrc-interactions/` folder: This subdirectory hosts APIs designed for interaction with the `IHRC729Contract`, facilitating operations related to IHRC (Hedera Improvement Request) standards. + + - `prng-interactions/` folder: Within this directory, you'll find APIs dedicated to interacting with the `PrngSystemContract`, which plays a crucial role in generating pseudo-random numbers. + +### b. Adding New System Contracts to the DApp + +#### b1. Folder structure + +When a new system contract is added to the DApp, main focus will shift to the `src/api/hedera/` folder. It is crucial to maintain a clear and structured folder organization. Each subdirectory within this folder should be allocated for a specific API category. Therefore, the incorporation of a new contract entails the creation of a dedicated folder to accommodate its related APIs. + +#### b2. Writing New APIs for Smart Contract Interaction + +When creating new APIs for smart contract interaction, it's important to adhere to certain guidelines and practices: + +- **Documenting API Methods**: It's crucial to thoroughly document each API method. For instance: + +```typescript +/** + * @dev Mints Hedera tokens and transfers them to another address. + * + * @dev Integrates tokenCreateCustomContract.mintTokenToAddressPublic() & tokenCreateCustomContract.mintNonFungibleTokenToAddressPublic() + * + * @param baseContract: ethers.Contract + * + * @param tokenType: 'FUNGIBLE' | 'NON_FUNGIBLE' + * + * @param hederaTokenAddress: string + * + * @param recipientAddress: string + * + * @param amountToMint: number + * + * @param metadata: string[] + * + * @return Promise + */ +``` + +- **Standard First Argument**: Note that all APIs interacting with smart contracts have their first argument set as `baseContract: Contract`. This is because the design of client components ensures that the deployed contract is passed as `baseContract` for API methods. + +- **Promise Return Type**: Most APIs interacting with smart contracts return a Promise compliant with the `ISmartContractExecutionResult` interface: + +These practices ensure consistency, clarity, and reliability in the development and usage of smart contract interaction APIs. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/app/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/app/index.md new file mode 100644 index 000000000..4eb1262cd --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/app/index.md @@ -0,0 +1,41 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/app/** Folder + +### a. Overview + +The **src/app/** folder is a pivotal addition introduced in Next.js 13, offering enhanced flexibility in configuring the UI through loading, error handling, and layout components. This directory serves as the cornerstone for route management and view rendering in a Next.js application. With the advent of Next.js 13, the `app/` folder brings about new conventions and practices that simplify the creation of pages, shared layouts, and templates. You can find more information about these conventions [here](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts). + +### b. Folder Structure + +- `page.tsx` file: This file serves as the primary or root UI component for the entire project. + +- `layout.tsx` file: This file represents the root shared layout for the entire project. It plays a crucial role in preserving state, maintaining interactivity, and avoiding unnecessary re-renders when navigating between multiple pages. + +- `activity/` folder: This folder corresponds to the `/activity` route. It follows a similar structure with a `page.tsx` file, representing the main UI component for the `/activity` route, and a `layout.tsx` file, serving as the shared layout specific to the `/activity` route. + +- `hedera/` folder: This folder represents the `/hedera` route. It does not include a `page.tsx` file, which means it won't be found when navigating to the `/hedera` route. Instead, it comprises a group of subdirectories, each dedicated to a specific smart contract exposed in the DApp. Again, each subdirectory contains its own `page.tsx` file, representing the main UI component for its respective route. + +### b. Adding New System Contracts to the DApp + +#### b1. Folder Structure + +Maintaining a well-structured folder organization is paramount. Each subdirectory within this folder should be designated for a specific contract or contract category. Consequently, introducing a new contract necessitates the creation of a dedicated folder to accommodate it. + +#### b2. `page.tsx` File Structure + +It's worth noting that all the `page.tsx` files located in these subdirectories share a common structure. They typically contain an imported component that serves as the main content for the route. For instance: + +```typescript +import HTS206Section from '@/sections/hts-hip-206'; + +const HTS206 = () => { + return ; +}; + +export default HTS206; +``` + +The imported components are section-level components defined in the `src/sections/` directory. This design allows for server-side rendering or data fetching when needed, as the root `page.tsx` can be used for such purposes, while the client-side logic remains within the section-level components. + +Consequently, when creating a new route for a new contract, it is recommended to adhere to this established code layout for consistency and maintainability. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/activity/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/activity/index.md new file mode 100644 index 000000000..433972bf7 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/activity/index.md @@ -0,0 +1,15 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/activity/** Folder + +The **src/components/activity/** folder serves as a repository for all the UI components associated with the `/activity` route within the application. + +Within this directory, you'll find the following subdirectories, each housing specific components: + +- `ActivityTransactionTable/` folder: Contains the `ActivityTransactionTable` component, which functions as a table displaying all the transactions executed during the current user session. + +- `ExtraOptionsButton/` folder: Encompasses the `ExtraOptionsButton` component, designed as a button that provides users with actionable options for performing operations on transactions such as deleting or exporting transactions. + +- `QueryResponseModal/` folder: Hosts the `QueryResponseModal` component, which serves as a modal window used to present response data for transactions with READONLY attributes. + +This organized structure ensures that UI components related to the `/activity` route are neatly categorized, enhancing code maintainability and readability. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/background-gradients/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/background-gradients/index.md new file mode 100644 index 000000000..14f82acb8 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/background-gradients/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/background-gradients/** Folder + +The **src/components/background-gradients/** folder is home to the `BgGradient` component. This component plays a pivotal role in providing the primary shared background gradients that are utilized consistently across the entire application. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/common/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/common/index.md new file mode 100644 index 000000000..ca21264a1 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/common/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/common/** Folder + +The **src/components/common/** folder functions as a central repository for a collection of shared functions that are reused across multiple main components. These shared functions encompass both UI code components and helper methods, enhancing code modularity and reusability. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/contract-interactions/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/contract-interactions/index.md new file mode 100644 index 000000000..d353d400a --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/contract-interactions/index.md @@ -0,0 +1,113 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/contract-interactions/** Folder + +### a. Overview + +The **src/components/contract-interactions/** folder plays a crucial role in hosting various UI components that facilitate user interactions with Hedera's system contracts. This folder is meticulously structured, with each subdirectory representing a group of related smart contracts. The subdirectory names correspond to the names of the smart contracts they represent. Within each of these subdirectories, a `methods/` folder exists, which, in turn, hosts further sub-folders representing the methods of the smart contracts. This structure is designed to align with the APIs offered in the corresponding smart contracts found in the `src/api/` folder. In some cases, closely related APIs are grouped within a single method component. + +Here is a detailed breakdown of the **src/components/contract-interactions/** subdirectories: + +- `erc` folder: This directory contains contract interaction UI components related to Ethereum-specific contracts (e.g., erc-20 or erc721). Since `erc` smart contracts require specific arguments for deployment, you'll find a `deployment/` folder here. The `deployment/` folder includes a UI component that simplifies the process of deploying `erc` contracts by allowing users to easily fill in the required arguments, such as `name` and `symbol`. In other smart contract folders (e.g., `erc-20/`, `erc-721/`), you'll encounter a `methods/` subdirectory housing various UI components designed to assist users in interacting with the corresponding contracts. + +- `exchange-rate/` folder: This directory contains contract interaction UI components for users to interact with the `ExchangeRatePrecompile` contract. + +- `hts/` folder: Within this directory, you'll find contract interaction UI components designed for user interactions with smart contracts related to the `Hedera Token Service` precompiled contract. The `shared/` subfolder contains common components, methods, and states shared among the contract interaction UI components in the `hts/` folder. The remaining subfolders correspond to specific system contracts related to the `Hedera Token Service`. There are four of them: `TokenCreateCustomContract`, `TokenManagementContract`, `TokenQueryContract`, and `TokenTransferContract`, mirroring the structure of the `token-create-custom`, `token-management-contract`, `token-query-contract`, and `token-transfer-contract` folders. Within these subfolders, you'll find a `methods/` subdirectory housing various API methods corresponding to each system contract. + +- `ihrc/` folder: This directory contains contract interaction UI components for users to interact with the `IHRC729Contract` contract. + +- `prng/` folder: This directory contains contract interaction UI components for users to interact with the `PrngSystemContract` contract. + +### b. Adding New System Contracts to the DApp + +#### b1. Folder structure + +When a new system contract is added to the DApp, it is crucial to maintain a clear and structured folder organization. Each subdirectory within this folder should be allocated for a specific system contract category. Therefore, the incorporation of a new contract entails the creation of a dedicated `contract` folder to accommodate its related contracts and methods. + +#### b2. deployment Folder (Optional) + +The deployment folder is an optional component, as some system contracts may not require arguments during deployment. If needed, you can create a sub-folder named `deployment/` within the respective `contract` folder to contain the deployment logic for the smart contract. You can refer to the [ERC20DeployField](../../../../../../../../src/components/contract-interaction/erc/deployment/ERCDeployField.tsx) as a reference when structuring this folder. + +#### b3. Methods Folder + +In the methods folder, each method API should have its dedicated folder. As different method APIs require different arguments, the UI layout may vary accordingly. However, all method UI components share common components, hooks, and methods. + +For instance, let's focus on the [FungibleTokenCreate](../../../../../../../../src/components/contract-interaction/hts/token-create-custom/methods/FungibleTokenCreate/index.tsx) UI component from the `token-create-custom/` contract folder. + +##### PageProps + +All method UI components share a common `PageProps` interface, which includes the `baseContract: Contract` property. This `baseContract` is passed in from the parent component and represents the deployed contract on the network. + +```typescript +interface PageProps { + baseContract: Contract; +} + +const FungibleTokenCreate = ({ baseContract }: PageProps) => { + ... +} +``` + +##### Generating States + +In each UI component, the first step is to generate states where you define all the necessary states for the component and method. + +##### handleRetrievingTransactionResultsFromLocalStorage Helper Method + +Next, you may encounter the usage of the `handleRetrievingTransactionResultsFromLocalStorage` helper method. + +```typescript +/** @dev retrieve token creation results from localStorage to maintain data on re-renders */ +useEffect(() => { +handleRetrievingTransactionResultsFromLocalStorage( + toaster, + transactionResultStorageKey, + setCurrentTransactionPage, + setTransactionResults +); +``` + +This method retrieves the list of transactions from `localStorage` and stores them in the component's current state, displaying them to users. Storing transactions in `localStorage` helps maintain data on re-renders. + +#### usePaginatedTxResults Custom Hook + +Right below, you'll find a custom hook called `usePaginatedTxResults`. + +```typescript +// declare a paginatedTransactionResults +const paginatedTransactionResults = usePaginatedTxResults(currentTransactionPage, transactionResultsToShow); +``` + +This hook automatically slices the main `transactionResults` list into smaller chunks (typically 10 records) and displays it in a paginated style. It updates itself when users click on the next or previous page buttons. + +#### handleInputOnChange Function + +```typescript +/** @dev handle form inputs on change */ +const handleInputOnChange = (e: any, param: string) => { + setParamValues((prev: any) => ({ ...prev, [param]: e.target.value })); +}; +``` + +This function simply updates form states when users input data. + +#### handleCreatingFungibleToken Function + +This is the main function acting as a bridge to transfer user-input data to the backend API method, which communicates with the deployed contracts on the network. Due to variations in method APIs, this function differs from one method API to another. + +#### useUpdateTransactionResultsToLocalStorage Custom Hook + +```typescript +/** @dev listen to change event on transactionResults state => load to localStorage */ +useUpdateTransactionResultsToLocalStorage(transactionResults, transactionResultStorageKey); +``` + +This hook automatically updates the `transactionResults` list in `localStorage` by listening to changes in the `transactionResults` state. + +#### useToastSuccessful Custom Hook + +You'll also find the `useToastSuccessful` custom hook, which displays a success message via a toast and resets all states if a transaction is successful. + +#### Return Statement + +Finally, within the return statement, you'll find the main UI component that showcases the entire layout of the method API. The layout may vary from one method API to another due to the diversity of method APIs. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/footer/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/footer/index.md new file mode 100644 index 000000000..0344865d5 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/footer/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/footer/** Folder + +The **src/components/footer/** folder houses the primary `Footer` component, which is utilized consistently throughout the entire application. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/navbar/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/navbar/index.md new file mode 100644 index 000000000..d0c35ca08 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/navbar/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/navbar/** Folder + +The **src/components/navbar/** folder houses the primary `Navbar` component, which is utilized consistently throughout the entire application. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/sidebar/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/sidebar/index.md new file mode 100644 index 000000000..753e59683 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/sidebar/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/sidebar/** Folder + +The **src/components/sidebar/** folder houses the primary `NavSideBar` component, which is utilized consistently throughout the entire application. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/toast/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/toast/index.md new file mode 100644 index 000000000..066e5ae89 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/toast/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/toast/** Folder + +The **src/components/toast/** folder houses the primary `CommonErrorToast` component, which is utilized consistently throughout the entire application. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/wallet-popup/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/wallet-popup/index.md new file mode 100644 index 000000000..1c7b22d9b --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/components/wallet-popup/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/components/wallet-popup/** Folder + +The **src/components/wallet-popup/** folder serves as the designated repository for the primary `WalletPopup` component. This component features a button that triggers a popup modal, providing a comprehensive display of information about the connected user. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/fonts/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/fonts/index.md new file mode 100644 index 000000000..70d933759 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/fonts/index.md @@ -0,0 +1,7 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/fonts/** Folder + +The **src/fonts/** folder serves as the repository for the primary fonts utilized throughout the entire project. Specifically, it features the Styrene A font family, which acts as the project's primary sans-serif font. This font family plays a pivotal role in defining the visual language and branding of the project. + +More information about Styrene A font family can be found [here](https://hederabrandcentral.frontify.com/d/Tmocz52AXpLj/brand-assets#/brand-assets/typography) diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/hooks/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/hooks/index.md new file mode 100644 index 000000000..185abd1da --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/hooks/index.md @@ -0,0 +1,15 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/hooks/** Folder + +The **src/hooks/** subdirectory hosts a series of custom hooks, each designed to "hook into" React's state and lifecycle mechanisms, enhancing the functionality and reusability of function components. + +Here is a breakdown of the **src/hooks/** subdirectories: + +- `useFilterTransactionsByContractAddress.tsx`: This file houses the `useFilterTransactionsByContractAddress` hook, which finds widespread use in all of the `contract-interaction` files. Its primary purpose is to filter transactions based on whether they match the `.sessionedContractAddress` attribute with the current `deployed contract address`. + +- `usePaginatedTxResults.tsx`: Within this file resides the `usePaginatedTxResults` hook, another essential component shared among the `contract-interaction` files. This hook is responsible for dividing the main `transactionResults` array into smaller pages, determined by the specified page size. + +- `useToastSuccessful.tsx`: The `useToastSuccessful` hook is found in this file and is employed extensively across the `contract-interaction` files. Its primary function is to display a toast notification, informing users of successful transaction processing. Additionally, it resets all relevant states utilized during the process. + +- `useUpdateLocalStorage.tsx`: In this file, you'll find the `useUpdateLocalStorage` hook, which is utilized in all of the `contract-interaction` files. Its primary role is to update the local storage with the newly received responses from smart contract interactions, ensuring data consistency across re-renders. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/libs/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/libs/index.md new file mode 100644 index 000000000..ede4c6f06 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/libs/index.md @@ -0,0 +1,11 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/libs/** Folder + +The **src/libs/** folder encompasses two essential UI libraries employed for the project's layout design: + +1. **Chakra UI**: Chakra UI is a versatile, modular, and highly accessible component library. It equips developers with a comprehensive set of building blocks essential for creating React applications. + +2. **Framer Motion**: Framer Motion stands as a production-ready motion library tailored for React, developed by Framer. It offers a straightforward yet potent framework for crafting animations, interactions, and gestures within React-based applications. + +These two libraries play a pivotal role in shaping the visual and interactive aspects of the project's user interface, contributing to its functionality and aesthetics. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/middleware.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/middleware.md new file mode 100644 index 000000000..e179ee8b5 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/middleware.md @@ -0,0 +1,31 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/middleware.tsx** File + +### Overview + +The **middleware.tsx** file functions as a module providing middleware capabilities for request handling within a Next.js application. Its primary responsibility lies in processing incoming requests and making routing decisions based on specific request properties. + +This middleware also plays a crucial role in ensuring that access to protected routes is only granted after users have connected their wallet to the DApp. + +### Adding New System Contracts to the DApp + +Within the `middleware.ts` file, you will encounter the `isProtectedRoute()` function. This function is employed to assess the `pathname` variable, determining whether it corresponds to a protected route. It accomplishes this by checking if the `pathname` is included in the `PROTECTED_ROUTES` constant variable, which can be found in the [constants.ts](../../../../../../src/utils/common/constants.ts) file. + +Introducing a new system contract to the DApp involves adding a dedicated route within the `src/app/hedera/` folder to showcase the contract. This new route is essentially designated as a protected route. To achieve this, simply include the new route in the `PROTECTED_ROUTES` array within the `constants.ts` file. For instance, if you're adding the `ERC1155Mock` contract with a new route, such as `/hedera/erc-1155/`, the updated `PROTECTED_ROUTES` array would look as follows: + +```typescript +export const PROTECTED_ROUTES = [ + '/hedera/overview', + '/hedera/hts-hip-206', + '/hedera/hrc-719', + '/hedera/exchange-rate-hip-475', + '/hedera/prng-hip-351', + '/hedera/erc-20', + '/hedera/erc-721', + '/hedera/erc-1155/', // New addition here + '/activity', +]; +``` + +This modification ensures that the new route corresponding to the `ERC1155Mock` contract is appropriately categorized as a protected route, aligning with the DApp's security and access control requirements. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/sections/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/sections/index.md new file mode 100644 index 000000000..cf4c4879b --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/sections/index.md @@ -0,0 +1,53 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/sections/** Folder + +### a. Overview + +The **src/sections/** folder serves as an organizational hub for a series of subdirectories, each housing `section-level` files. These `section-level` components are integral parts of the main UI components specified in the `page.tsx` files located in the `src/app/` subdirectories. + +Here is a breakdown of the **src/sections/** subdirectories: + +- `activity/` folder: This folder contains the `ActivitySection` UI component, responsible for showcasing the main activity page of the DApp. It aggregates all transactions conducted during the session and presents them to users. + +- `erc-20/` folder: In this directory, you'll find the `ERC20Section` UI component, which provides essential information about the `ERC20Mock` contract. Additionally, it features a user interface for interacting with the `ERC20Mock` smart contract. + +- `erc-721/` folder: This directory houses the `ERC721Section` UI component, which presents vital information about the `ERC721Mock` contract. It also offers a user-friendly interface for interacting with the `ERC20Mock` smart contract. + +- `exchange-rate-hip-475/` folder: Within this folder, you'll encounter the `HIP475Section` UI component, designed to display crucial details about the `ExchangeRatePrecompile` contract. It also includes an interface for interacting with the `ExchangeRatePrecompile` smart contract. + +- `hrc-719/` folder: This directory hosts the `IHRC719Section` UI component, which provides essential information about the `IHRC729Contract` contract. It features a user interface for interacting with the `IHRC729Contract` smart contract. + +- `hts-hip-206/` folder: Found within this directory is the `HTS206Section` UI component, responsible for displaying essential information about the four example contracts: `TokenCreateCustomContract`, `TokenManagementContract`, `TokenQueryContract`, and `TokenTransferContract`. It also includes an interface for interacting with these smart contracts. + +- `landing/` folder: This folder contains the `landing` UI component, responsible for displaying the landing page of the DApp. + +- `overview/` folder: Within this directory resides the `OverviewSection` UI component, which is responsible for displaying the landing page of the DApp after users have connected their wallets. + +- `prng-hip-351/` folder: This directory houses the `HIP351Section` UI component, which offers vital information about the `PrngSystemContract` contract. Additionally, it includes an interface for interacting with the `PrngSystemContract` smart contract. + +These `section-level` components are crucial elements of the DApp's user interface, providing users with access to various functionalities and information related to smart contracts and DApp activities. + +### b. Adding New System Contracts to the DApp + +#### b1. Folder Structure + +When introducing new system contracts to the DApp, adhering to a well-organized folder structure is of utmost importance. Each subdirectory within this folder should be allocated for a specific contract section. Consequently, incorporating a new contract entails the creation of a dedicated folder to house all related components and assets. + +#### b2. Page Structure + +In line with established conventions, new contract page should exhibit the following elements: + +- **Contract Title**: Display the title of the contract. +- **HIP Link**: If applicable, provide a link to the corresponding `HIP` (Hedera Improvement Proposal). +- **Overview**: Offer a concise overview of the contract's purpose and functionality. +- **GitHub Link**: Include a link to the contract's repository on GitHub. +- **ContractInteraction Component**: All contract pages share a common `ContractInteraction` component, which is crucial for evaluating the contract and dynamically generating the layout based on the contract's methods and APIs. For instance: + +```typescript + +``` + +This component plays a pivotal role in interacting with the contract, providing users with access to its functionalities and features. + +Maintaining this consistent page structure ensures clarity and usability for users navigating the DApp and engaging with various system contracts. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/styles/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/styles/index.md new file mode 100644 index 000000000..2ba84973b --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/styles/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/styles/** Folder + +The **src/styles/** folder serves as the repository for the global styles that define the visual appearance and consistency of the entire project. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/types/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/types/index.md new file mode 100644 index 000000000..a6c588fb0 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/types/index.md @@ -0,0 +1,5 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/types/** Folder + +The **src/types/** folder serves as the repository for all essential types and interfaces utilized throughout the entire project. This section plays a pivotal role in defining the structure and data models employed across the codebase. diff --git a/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/utils/index.md b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/utils/index.md new file mode 100644 index 000000000..39f7cf303 --- /dev/null +++ b/system-contract-dapp-playground/docs/source-code-document/codebase-structure/2.codebase-walkthrough/src/utils/index.md @@ -0,0 +1,11 @@ +# Source Code Documentation + +## Codebase Walkthrough - **src/utils/** Folder + +The **src/utils/** folder is dedicated to housing utility-level code components essential for the project's functionality. Within this directory, you'll find: + +- Shared Common Constants +- Helper Functions +- DApp's Metadata + +These utilities play a crucial role in facilitating various aspects of the project, including data manipulation, consistency, and overall functionality. diff --git a/system-contract-dapp-playground/package.json b/system-contract-dapp-playground/package.json index 4e2ac5ecc..2551aa494 100644 --- a/system-contract-dapp-playground/package.json +++ b/system-contract-dapp-playground/package.json @@ -17,7 +17,7 @@ "build": "next build", "start": "next start", "lint": "next lint", - "prerequisite-check": "ts-node ./scripts/prerequisite-check.ts", + "prerequisite-check": "ts-node ./prerequisite-check/scripts/index.ts", "test:watch": "jest --watch", "test": "jest" }, diff --git a/system-contract-dapp-playground/contracts-info/index.ts b/system-contract-dapp-playground/prerequisite-check/contracts-info/index.ts similarity index 100% rename from system-contract-dapp-playground/contracts-info/index.ts rename to system-contract-dapp-playground/prerequisite-check/contracts-info/index.ts diff --git a/system-contract-dapp-playground/scripts/prerequisite-check.ts b/system-contract-dapp-playground/prerequisite-check/scripts/index.ts similarity index 99% rename from system-contract-dapp-playground/scripts/prerequisite-check.ts rename to system-contract-dapp-playground/prerequisite-check/scripts/index.ts index 8307eefa4..cc7b60130 100644 --- a/system-contract-dapp-playground/scripts/prerequisite-check.ts +++ b/system-contract-dapp-playground/prerequisite-check/scripts/index.ts @@ -23,7 +23,7 @@ const path = require('path'); const getHederaSmartContractAssetsFunc = require('../contracts-info'); /** @dev resolves the root path of the hedera smart contracts repo */ -const HederaSmartContractsRootPath = path.resolve(__dirname, '..', '..'); +const HederaSmartContractsRootPath = path.resolve(__dirname, '..', '..', '..'); if ( !fs.existsSync(`${HederaSmartContractsRootPath}/artifacts`) || diff --git a/system-contract-dapp-playground/src/components/contract-interaction/exchange-rate/deployment/ExchangeRateDeployField.tsx b/system-contract-dapp-playground/src/components/contract-interaction/exchange-rate/deployment/ExchangeRateDeployField.tsx deleted file mode 100644 index 3c3e70ed0..000000000 --- a/system-contract-dapp-playground/src/components/contract-interaction/exchange-rate/deployment/ExchangeRateDeployField.tsx +++ /dev/null @@ -1,94 +0,0 @@ -/*- - * - * Hedera Smart Contracts - * - * Copyright (C) 2023 Hedera Hashgraph, LLC - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - */ - -import Image from 'next/image'; -import { useToast } from '@chakra-ui/react'; -import { Dispatch, SetStateAction, useState } from 'react'; -import { CommonErrorToast } from '../../../toast/CommonToast'; -import HederaCommonTextField from '../../../common/components/HederaCommonTextField'; - -interface PageProps { - isDeploying: boolean; - setDeployedParams: Dispatch; - setDidDeployStart: Dispatch>; -} - -const ExchangeRateDeployField = ({ isDeploying, setDidDeployStart, setDeployedParams }: PageProps) => { - const toaster = useToast(); - const [value, setValue] = useState(''); - - const handleDeploy = async () => { - // stop user when the param is empty - if (value === '') { - CommonErrorToast({ - toaster, - title: 'Cannot deploy contract', - description: 'Toll fee cannot be empty', - }); - return; - } - - // update global deployedParam - setDeployedParams([value]); - - // trigger deploySmartContract API - setDidDeployStart(true); - }; - - return ( -
- - - {/* deploy button */} - -
- ); -}; - -export default ExchangeRateDeployField;