How to List your Project on the Moonbeam DApp Directory¶

Introduction to The Moonbeam DApp Directory¶

The Moonbeam ecosystem comprises two distinct production networks: Moonbeam and Moonriver. Each network has its own dedicated DApp Directory, maintained by the Moonbeam Foundation. These directories categorize projects spanning from DeFi to NFTs to gaming, providing users with comprehensive access to diverse applications.

You'll supply core project details like name, description, and relevant links when adding your project. Depending on your project type, you may include additional data such as on-chain stats and token information.

Despite the distinction between the Moonbeam and Moonriver DApp directories, the submission process remains the same. To list your project on the DApp Directory, you must submit a pull request to the Moonbeam Foundation's App Directory Data repository on GitHub. This guide outlines the necessary data and formatting specifics for your submission.

Overview of the Project Data¶

There are four main sources of data that are used for a project's listing in the Moonbeam DApp Directory:

• Core Project Data - core project data such as descriptions, logos, and screenshots. This data also includes IDs used to query data from external platforms
• Active Users and Transaction Volume - on-chain data based on smart contract activity for all of the contracts associated with the project. Data is discovered via the use of contract labeling in Moonscan, which is then indexed by Web3Go and consumed by the DApp Directory
• TVL Data - TVL data for the protocol, sourced from the project's listing on DefiLlama
• Project Token Information - token information, which is sourced from the project's listing on CoinGecko

Prerequisites for Using External Data Sources¶

Before pulling data from the mentioned sources, certain prerequisites must be fulfilled. However, it's worth noting that these steps may not apply to all project types. For instance, in the case of wallets, where there are no smart contracts, the DApp Directory is currently unable to display user and transaction activity data.

Configure the Data Source for Active Users and Transaction Volume¶

For projects that have smart contracts deployed on Moonbeam or Moonriver, it is important that those contracts can be linked to the DApp Directory project data.

The end-to-end flow for linking smart contract activity to the DApp Directory is as follows:

1. The smart contract owner fills in the form to label contracts on Moonscan
2. The contracts become labeled in Moonscan
3. Periodically, the entire list of labeled contracts is exported and transmitted to Web3Go to be ingested
4. Every hour, Web3Go loads smart contract activity within Moonbeam and Moonriver and runs a job to index this data by the labels

To get your project's smart contracts properly labeled on Moonscan, please refer to Web3Go's documentation on the Labeling Structure and How to Submit Contract Information on Moonscan.

Once you've labeled your smart contracts and are ready to submit your project to the DApp Directory, configuring the Directory to utilize your smart contract data becomes straightforward. You'll only need the Project component of your labeled contracts.

Consider the following example project with two smart contracts: a Comptroller and a Router recently updated to a new version.

To submit your project to the Moonbeam DApp Directory, ensure you have your Project name ready, identified here as My Project.

If you're ready to add your project to the DApp Directory, skip to the How to Submit Your Project Listing section.

Configure the Data Source for TVL¶

If the project represents a DeFi protocol with TVL (whereby value is locked in the protocol's smart contract), it is possible to display TVL in the Moonbeam DApp Directory.

TVL data is pulled from DefiLlama, so you must list your project there. To get your project listed, please refer to DefiLlama's documentation on How to list a DeFi project.

After listing your project, you can easily configure the DApp Directory to pull data from DefiLlama. To do so, you'll need the DefiLlama identifier, which you can find in the URL for your protocol's page. For example, the URL for Moonwell's page is https://defillama.com/protocol/moonwell, so the identifier is moonwell.

If you have the identifier and are ready to submit your project to the Moonbeam DApp Directory, skip to the How to Submit Your Project Listing section.

Configure the Data Source for Project Token Information¶

If a project has a token, it is possible to display the name of the token, current price, and contract in the DApp Directory.

However, the data is pulled from CoinGecko, so the project's token must be listed there. If your token is not listed there, you can complete CoinGecko's Request Form to initiate the listing process.

Assuming your project's token is listed there, you must obtain the CoinGecko API ID value. You can find the API ID value in the Information section of the token's page on CoinGecko. For example, the API ID on Moonwell's token page is moonwell-artemis.

If you have the CoinGecko ID and are ready to submit your project to the Moonbeam DApp Directory, you can continue to the next section.

How to Submit Your Project Listing¶

As mentioned, you must submit a pull request to the Moonbeam Foundation's GitHub repository that holds the DApp Directory's data. Before getting started, it's worth noting that to expedite the review process, the GitHub user who submits the pull request is recommended to be a major contributor to the project's GitHub so that the Moonbeam Foundation can quickly verify that they represent the project. You can check out the Review Process section for more information.

To begin, you have two options for adding your project information to the app-directory-data repository on GitHub. You can utilize GitHub's browser-based editor, which offers a user-friendly interface.

Or you can clone the repository locally and make modifications using your preferred code editor, in which you can use the following command to clone the repository:

git clone https://github.com/moonbeam-foundation/app-directory-data.git

Once you've cloned the project, you can create a new branch to which you will add all of your changes. To do this on the browser-based editor, take the following steps:

1. Click on the current branch name in the bottom left corner
2. A menu will appear at the top of the page. Enter the name of your branch
3. Click Create new branch...

The page will reload, and your branch name will now be displayed in the bottom left corner.

Projects with Deployments on Moonbeam and Moonriver¶

If a project is deployed to both Moonbeam and Moonriver, there are two different options available:

• Create a separate project structure for each deployment
• Use a single project structure and modify the project data file for both projects

Separate project structures should be used if:

• The two deployments have distinct representations in DefiLlama (i.e., two distinct identifiers)
• The project has two different tokens, one native to Moonbeam and one native to Moonriver

Otherwise, either option may be used.

Set Up the Folder Structure for Your Project¶

All configurations for each project listed in the DApp Directory are stored in the projects folder.

To get started, you must have a name that uniquely and properly identifies your project. Using your project name, you can take the following steps:

1. Create a new directory for your project using your unique project name
2. In your project directory, you'll need to create:
   1. A project data file is a JSON file that defines all your project data and contains references to the images stored in the logos and screenshots folders. The list of fields you can use to define your data, with descriptions, is outlined in the next section. The file must be named using your unique project name
   2. A logos folder where your project logo images are stored
   3. (Optional) A screenshots folder where screenshots for the project are stored

my-project
├── my-project.json
├── logos
│   ├── my-project-logo-small.jpeg
│   └── my-project-logo-full.jpeg
└── screenshots
    ├── my-project-screenshot1-small.jpeg
    ├── my-project-screenshot1-full.jpeg
    ├── my-project-screenshot2-small.jpeg
    └── my-project-screenshot2-full.jpeg

With the foundational file structure in place, you're ready to populate the necessary information for your project submission.

Add Information to the Project Data File¶

Your project's data file is where you'll add all the information for your project. The file permits the following top-level properties:

{
    "id": "moonwell",
    "slug": "moonwell",
    "name": "Moonwell",
    "category": "lending",
    "coinGeckoId": "moonwell-artemis",
    "chains": ["moonbeam"],
    "web3goIDs": ["Moonwell Artemis"],
    "logo": {
        "small": {
            "fileName": "moonwell-logo-small.jpeg",
            "width": 40,
            "height": 40,
            "mimeType": "image/jpeg"
        },
        "large": {
            "fileName": "moonwell-logo-large.jpeg",
            "width": 400,
            "height": 400,
            "mimeType": "image/jpeg"
        },
        "full": {
            "fileName": "moonwell-logo-full.jpeg",
            "width": 3000,
            "height": 3000,
            "mimeType": "image/jpeg"
        }
    },
    "shortDescription": "Lending, borrowing, and DeFi protocol built on Moonbeam and Moonriver",
    "description": "Moonwell is an open lending, borrowing, and decentralized finance protocol built on Moonbeam and Moonriver. Moonwell’s composable design can accommodate a full range of DeFi applications in the greater Polkadot and Kusama (DotSama) ecosystem.\r\n\r\nOur first deployment will be on Kusama’s Moonriver, the sister network of Polkadot’s Moonbeam. Moonriver is where new products are expected to be incubated and developed prior to being deployed on Moonbeam.",
    "tags": ["Lending", "DeFi"],
    "contracts": [
        {
            "contract": "0x511ab53f793683763e5a8829738301368a2411e3",
            "chain": "moonbeam",
            "name": "WELL Token"
        }
    ],
    "urls": {
        "website": "https://moonwell.fi/",
        "try": "https://moonwell.fi/",
        "twitter": "https://twitter.com/MoonwellDeFi",
        "medium": "https://moonwell.medium.com/",
        "telegram": "https://t.me/moonwellfichat",
        "github": "https://github.com/moonwell-open-source",
        "discord": "https://discord.gg/moonwellfi"
    },
    "screenshots": [
        {
            "small": {
                "fileName": "moonwell-screenshot-small1.png",
                "width": 429,
                "height": 200,
                "mimeType": "image/png"
            },
            "full": {
                "fileName": "moonwell-screenshot-full1.png",
                "width": 514,
                "height": 300,
                "mimeType": "image/png"
            }
        },
        {
            "small": {
                "fileName": "moonwell-screenshot-small2.png",
                "width": 429,
                "height": 200,
                "mimeType": "image/png"
            },
            "full": {
                "fileName": "moonwell-screenshot-full2.png",
                "width": 1716,
                "height": 800,
                "mimeType": "image/png"
            }
        },
        {
            "small": {
                "fileName": "moonwell-screenshot-small3.png",
                "width": 429,
                "height": 200,
                "mimeType": "image/png"
            },
            "full": {
                "fileName": "moonwell-screenshot-full3.png",
                "width": 1054,
                "height": 637,
                "mimeType": "image/png"
            }
        },
        {
            "small": {
                "fileName": "moonwell-screenshot-small4.png",
                "width": 429,
                "height": 200,
                "mimeType": "image/png"
            },
            "full": {
                "fileName": "moonwell-screenshot-full4.png",
                "width": 1365,
                "height": 436,
                "mimeType": "image/png"
            }
        }
    ],
    "projectCreationDate": 1644828523000
}

Category and Tags¶

The currently supported values for category and tags are:

• DeFi
• Dex
• Bridges
• Lending
• NFTs
• Gaming
• Social
• Wallets
• DAO
• Other

URLs¶

The urls property name/value pairs are used so a project can provide links to their website, socials, etc.

The following table lists the supported urls properties:

The format of the property name/value pairs should follow the JSON standard, for example:

"urls": {
    "website": "https://moonbeam.network/",
    "try": "https://docs.moonbeam.network/",
    "twitter": "https://twitter.com/MoonbeamNetwork"
}

Logos¶

The logos property of the main project data file is a map of image sizes (i.e., small, large, full) to corresponding image JSON objects. The image JSON object contains the display properties for the given image.

The following table lists the properties of the image JSON object:

Currently, only the small size is utilized, and the dimensions for small logos should be 40x40 pixels.

Here is an example showing the structure of the logo property that supplies small and full logos:

"logo": {
    "small": {
        "fileName": "my-project-logo-small.jpeg",
        "width": 40,
        "height": 40,
        "mimeType": "image/jpeg"
    },
    "full": {
        "fileName": "my-project-logo-full.jpeg",
        "width": 3000,
        "height": 3000,
        "mimeType": "image/jpeg"
    }
}

Screenshots¶

The screenshots property of the main project data file is an array of maps. Each map in the array is for a specific screenshot.

However, different-sized images for each screenshot should be supplied so that different sizes can be used in different contexts (e.g., thumbnails vs full-sized images). Thus, for each screenshot, there is a map of image sizes (i.e., small, large, full) to corresponding image JSON objects. The image JSON object contains the display properties for the given image.

The following table lists the properties of the image JSON object:

Here is an example showing the structure of the screenshot property for two screenshots (screenshot1 and screenshot2):

"screenshots": [
    {
        "small": {
            "fileName": "my-project-screenshot1-small.png",
            "width": 429,
            "height": 200,
            "mimeType": "image/png"
        },
        "full": {
            "fileName": "my-project-screenshot1-full.png",
            "width": 514,
            "height": 300,
            "mimeType": "image/png"
        }
    },
    {
        "small": {
            "fileName": "my-project-screenshot2-small.png",
            "width": 429,
            "height": 200,
            "mimeType": "image/png"
        },
        "full": {
            "fileName": "my-project-screenshot2-full.png",
            "width": 1716,
            "height": 800,
            "mimeType": "image/png"
        }
    }
]

Contracts¶

A list of contracts for the project. Currently, this is used only for token contracts.

The smart contracts that make up the protocol are sourced from Moonscan based on tagging, so they do not need to be listed here. If you have not properly labeled your contracts or are unsure if they are labeled according to the Moonbeam community standard, please refer to the Configure the Data Source for Active Users and Transaction Volume section.

The following table lists the properties found in the contract JSON object:

Here is a contracts array with a single smart contract for the WGLMR token:

"contracts": [
    {
        "contract": "0xAcc15dC74880C9944775448304B263D191c6077F",
        "chain": "moonbeam",
        "name": "Wrapped GLMR Token"
    }
]

Submit a Pull Request¶

After you've populated the project data file and added your logos and screenshots, you should be ready to submit your pull request.

From the web-based editor, take the following steps to commit your changes to the app-directory-data repository:

1. Click on the Source Control tab, which should show you how many pages have been added or changed
2. Review the files under the Changes section. Click the + button next to Changes, or as you review each file, click the + button next to the file name to add them to the list of Staged Changes

All of your files should now be under the Staged Changes section. All you have to commit and push the changes are:

1. Enter a descriptive commit message, such as "Add My Project", making sure to use your actual project name
2. Click Commit & Push

Now that you've committed the changes, you'll need to head over to the app-directory-data repository and open a pull request against the develop branch:

1. At the top of the repository page, click Compare and Pull button displayed on the banner, or
2. If the banner is not there anymore, you'll need to select your branch from the branches dropdown
3. Click the Contribute dropdown
4. Click the Open pull request button

You'll be taken to the Comparing changes page, where you'll need to:

1. Make sure that you are merging your branch into the develop branch, which is the base branch
2. Add a title
3. Add a description of the changes
4. Click Create pull request

The Review Process¶

Submitted pull requests will be reviewed bi-weekly by the Moonbeam Foundation. During the review, and especially for new projects, the Foundation may have to verify that the GitHub user who created the pull request is a contributor and/or represents the specific project. One way projects can expedite this process is if the submitter's GitHub account is also a major contributor to the project itself on GitHub. Alternatively, teams should leave a note in the pull request comments indicating how we can get in touch with project team members to verify.

A comment will be added to the pull request if any changes are requested. After your pull request has been approved, it will be merged, and your project will be added to the Moonbeam DApp Directory!

How to Update Your Project Listing¶

As your project evolves, you may need to update your project's listing or images related to your listing. You can create a new branch for your changes, find and modify your existing project's data from the root projects directory, and make the desired changes.

If you are no longer using a logo or screenshot, please remember to remove it from the logos or screenshots directory.

Once your changes have been made, you must follow the same instructions in the Submit a Pull Request section so the changes can be reviewed by the Moonbeam Foundation. Please note that pull requests are reviewed on a bi-weekly basis, so if the update is urgent, you can create a forum post asking for assistance.