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 ./src/mintlists/ directory.

Mintlist management also relies on two other Orca packages

• token-sdk - SDK utilities and classes for working with tokens
• mintlist-cli - CLI tool used by the mintlist repository for generating code and automating token management - e.g. scripts for adding and removing tokens

Mintlist Types

We currently maintain two mintlists which represent different types of business logic. Tokens that are in neither list will not be searchable or visible in our web app until we implement arbitrary token support in the future.

Orca Default List

orca-default.mintlist.json

This list represents what our web app considers the "whitelisted" tokens. Tokens in this list will be visible by default in our web app (e.g. token auto-complete drop-down, API endpoint).

Presence in the default lists takes priority over the extended list - if a mint is in both lists, it will be considered "whitelisted".

Orca Extended List

orca-extended.mintlist.json

Tokens that are only visible by default in our web app but NOT "whitelisted" tokens.

This list is currently automatically updated every 6 hours via the Auto Update action. This pulls the newest Solana token list from CoinGecko and adds any new mints that are detected.

Managing tokens

Here are the common actions to modify mintlists.

How to add whitelisted tokens:

• Add Mint GitHub Action
• Click on "Run Workflow" on the right-hand side
• Branch: main
• Mintlist to add mints to: orca-default.mintlist.json
• space separated mints to add: mint1 mint2 ...

How to add non-whitelisted tokens:

• Add Mint GitHub Action
• Click on "Run Workflow" on the right-hand side
• Branch: main
• Mintlist to add mints to: orca-extended.mintlist.json
• space separated mints to add: mint1 mint2 ...

How to un-whitelist tokens:

Note that if a token is removed from the default list and does not exist in the extended list, it will completely disappear from the UI. If we still want the token to appear in the UI but only be un-whitelisted, the token needs to exist in the extended list.

• Remove Mint GitHub Action
• Click on "Run Workflow" on the right-hand side
• Branch: main
• Mintlist to remove mints from: orca-default.mintlist.json
• space separated mints to remove: mint1 mint2 ...

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

• Currently only by manually modifying ./src/override.json
• Open PR with changes against main

File Structure

* = generated code
.
└── orca-mintlists/
    ├── .github/
    │   └── workflows/
    ├── bin/
    ├── dist*/
    │   └── <contents published to NPM>
    ├── src/
    │   ├── mintlists/
    │   │   ├── orca-default.mintlist.json
    │   │   └── orca-extended.mintlist.json
    │   ├── tokenlists*/
    │   │   └── <generated based on mintlists>
    │   ├── overrides.json
    │   └── index.ts*
    └── package.json

Changes can be made manually - see example PR https://github.com/orca-so/orca-mintlists/pull/1.

Whenever changes are detected on the main branch in any of the mintlist JSON files, we generate a new tokenlist from the mints. The tokenlist is used for caching on the client-side to prevent expensive fetches when first loading a large list of mints.

Once the tokenlist(s) are generated, we generate an index.ts file that exports all of the JSON files and compiles the package into the dist/ folder. A new version is then published as an NPM package that contains the latest mintlists and tokenlists. Clients use the latest NPM tag to pull in new changes on a set interval.

In the future, we can move the management of the JSON files from NPM to an on-chain solution like a Solana contract + Arweave.

Setting up the Repository

This repository requires the following secrets for the bump-and-publish GitHub workflow.

• SOLANA_NETWORK: Solana RPC URL used for fetching token metadata
• NPM_ACCESS_TOKEN: Access token used for publishing NPM packages
• CG_API_KEY: Optional - API key used for fetching token metadata

Also need to set up the following variable

• MINTLIST_CLI: mintlist-cli package version - e.g. @orca-so/[email protected]

Versioning

Once mintlist changes are detected in the main branch, the package version will automatically be updated in the following manner

• Major - When a mintlist is added or removed from the mintlists directory.
• Minor - When a mint is removed from at least one mintlist.
• Patch - When a mint is added to at least one mintlist or an overrides change is detected.