npm package: @orca-so/orca-mintlists
Description: Orca Mintlists
Latest version: 1.0.3

# Orca Mintlists

This is the repository for managing SPL tokens frequently used by Orca which replaces the Mongo DB
backed token database. Here we only manage lists of mint addresses, and there can be multiple lists
managed in the repository in the `./assets/mintlists/` directory.

Mintlist management also relies on two other Orca packages:

- [`token-sdk`](https://github.com/orca-so/orca-sdks/tree/main/packages/token-sdk) - SDK utilities and classes for working with tokens
- [`mintlist-cli`](https://github.com/orca-so/orca-sdks/tree/main/packages/mintlist-cli) - CLI tool used by the mintlist repository for formatting and managing mintlists - e.g. scripts for adding and removing tokens

## Automatic Deployments

- Any changes made in this repository on the `main` branch will automatically be deployed to Orca's
  [CloudFlare Pages](https://dash.cloudflare.com/916f0c7dee94a702ceec8bc0128eb2c6/pages/view/orca-mintlists) `orca-mintlists` deployment.
- The latest CF Pages deployment is configured to publish the `/assets` directory to https://mintlists.orca.so
- Clients can include `fetchMintlist` or `fetchOverrides` methods from this repository to programmatically fetch the latest updates by using the `@orca-so/orca-mintlists` NPM package. This is what our UI does.

## Mintlist Types

We currently maintain three mintlists which represent different types of business logic.

### Orca Default List

`orca-default.mintlist.json`

This list is rarely updated, and mints on this are preferred as legitimate tokens when detecting for imitators - AKA major Solana ecosystem tokens.

### Orca Extended List

`orca-extended.mintlist.json`

Tokens that have not been flagged as imitating other tokens, and tokens on this list will be displayed with no token warnings - AKA “whitelisted” tokens.

### Orca Unsupported List

`orca-unsupported.mintlist.json`

Tokens that are unsupported by Orca and hidden excluded in the UI.

## Managing tokens

Here are [video guides](https://www.notion.so/orcaso/Managing-Orca-Mintlists-0fd2e2c72b0549efa940608e4dfef24d?pvs=4#7e6bafb719274b6798eee71d2f88fb1e) on how to manage tokens.

### How to add tokens to a mintlist:

- [Add Mint GitHub Action](https://github.com/orca-so/orca-mintlists/actions/workflows/add-mints.yml)
- Click on "Run Workflow" on the right-hand side
- Branch: `main`
- Select appropriate mintlist to modify
- space separated mints to add: `mint1 mint2 ... `

### How to remove tokens from a mintlist:

- [Remove Mint GitHub Action](https://github.com/orca-so/orca-mintlists/actions/workflows/remove-mints.yml)
- Click on "Run Workflow" on the right-hand side
- Branch: `main`
- Select appropriate mintlist to modify
- space separated mints to remove: `mint1 mint2 ... `

### How to change(override) symbol or logo of tokens:

- Check out this repository
  ```
  git clone git@github.com:orca-so/orca-mintlists.git
  ```
- Make sure you have `yarn` installed, and then run `yarn` at the root.
  - https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable
- Check out a new branch
  ```
  git checkout -b tmoc/new-override
  ```
- Make the necessary changes to `overrides.json`
- Run `yarn fmt`
- Commit your changes and push to the repository
  ```
  git commit -am "Adding overrides for mint XYZ"
  git push origin tmoc/new-override
  ```
- Navigate to the repository and create a PR for your branch
- Review and merge as needed

## Notes

- The `main` branch cannot be directly modified. Please make changes in a separate branch and open a Pull Request.
- There is a lint check that enforces alphabetical sorting of mints in both the mintlists and overrides file. You can use the `yarn fmt` command to automatically sort files after you make changes.