@perspectivefi/token-list 1.26.0 → 1.26.7

package/README.md

@@ -1,113 +1,296 @@
 # Spectra Token List
 
-## Overview
+A comprehensive token registry for the Spectra Finance ecosystem, providing standardized metadata for tokens, ERC4626 wrappers and protocols across multiple networks.
 
-As Spectra, we use this repository as source of the tokens & platforms for our Web3 app as well as other services. This
-list is updated regularly as new tokens are added to the platform.
+**App**: https://app.spectra.finance  
+**Package**: `@perspectivefi/token-list`
 
-#### Spectra App: https://app.spectra.finance
+-   [Installation](#installation)
+-   [Usage](#usage)
+-   [Data Structure](#data-structure)
+-   [Contributing](#contributing)
+    -   [Adding Tokens](#adding-tokens)
+    -   [Adding ERC4626 Wrappers](#adding-erc4626-wrappers)
+    -   [Adding Protocols](#adding-protocols)
+-   [Schema Validation](#schema-validation)
+-   [Supported Networks](#supported-networks)
+-   [Development](#development)
 
-## Tokens and Protocols
+## Installation
 
--   [Spectra Tokens](src/tokens/spectraTokens.json)
--   [Spectra ERC4626 Wrappers](src/tokens/erc4626Wrappers.json)
--   [Protocols](src/protocols/protocolList.json)
--   [Curators](src/curators/curatorList.json)
+```bash
+npm install @perspectivefi/token-list
+# or
+yarn add @perspectivefi/token-list
+```
 
-## How to add a token
+## Usage
 
-Expected structure - `src/tokens/spectraTokens.json`
+```typescript
+import {
+    spectraTokens,
+    erc4626Wrappers,
+    protocolList,
+} from "@perspectivefi/token-list"
+```
 
-| chainId | address                                    | symbol | name          | decimals | logoURI                  | extensions                                                  |
-| ------- | ------------------------------------------ | ------ | ------------- | -------- | ------------------------ | ----------------------------------------------------------- |
-| 1       | 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | KweETH | Wrapped Ether | 18       | /images/tokens/weETH.svg | underlying, ibtRoutes, protocol, faucetAddress, aprEndpoint |
+## Data Structure
 
-### Steps:
+### Core Resources
 
-1. Create a new branch from the `main` with the name `chore/token-<token-symbol>-<chain-id>`
-2. Add the token to the `src/tokens/spectraTokens.json` file
+| Resource      | Description                                                             | Build Output                      |
+| ------------- | ----------------------------------------------------------------------- | --------------------------------- |
+| **Tokens**    | Individual token metadata stored in `/src/tokens/{chainId}/{address}/`  | `src/tokens/build.json`           |
+| **Wrappers**  | ERC4626 wrapper metadata stored in `/src/wrappers/{chainId}/{address}/` | `src/wrappers/build.json`         |
+| **Protocols** | Protocol configurations and multipliers                                 | `src/protocols/protocolList.json` |
 
-Example:
+### Token Structure
 
-```json
-[
-  ...
-  {
-    "chainId": 1,
-    "address": "0x4104b135dbc9609fc1a9490e61369036497660c8",
-    "name": "Spectra",
-    "symbol": "APW",
-    "decimals": 18,
-    "logoURI": "images/tokens/apw.svg"
-  }
-]
+Each token is stored as an individual directory containing:
+
+```
+src/tokens/{chainId}/{address}/
+├── index.json    # Token metadata
+└── logo.{svg|png} # Token logo
 ```
 
-3. Add the token logo to the `src/images/tokens` folder (use .png or .svg format)
-4. Commit the changes with the message: `chore: add <token-symbol>, chainId: <chain-id>`
-5. Create a pull request
-6. Once the PR is approved, the token will be added to the list and included in the Spectra platform in the next build.
-7. Done
+## Contributing
+
+We welcome contributions! Please follow the guidelines below for adding new tokens, wrappers, or protocols.
+
+### Adding Tokens
+
+**File Structure**: `src/tokens/{chainId}/{address}/index.json`
+
+#### Required Fields
+
+| Field      | Type   | Description               | Example                                        |
+| ---------- | ------ | ------------------------- | ---------------------------------------------- |
+| `chainId`  | number | Network chain ID          | `1`                                            |
+| `address`  | string | Token contract address    | `"0x4104b135dbc9609fc1a9490e61369036497660c8"` |
+| `name`     | string | Human-readable token name | `"Spectra"`                                    |
+| `symbol`   | string | Token symbol              | `"APW"`                                        |
+| `decimals` | number | Token decimals (1-18)     | `18`                                           |
+| `logoURI`  | string | Path to token logo        | `"/images/tokens/1/0x4104...c8.svg"`           |
+
+#### Optional Extensions
+
+| Field         | Type     | Description                                       |
+| ------------- | -------- | ------------------------------------------------- |
+| `tags`        | string[] | Token categories (`["stable", "liquid-staking"]`) |
+| `underlying`  | string   | Underlying asset address                          |
+| `protocol`    | string   | Associated protocol name                          |
+| `aprEndpoint` | string   | API endpoint for APR data                         |
+| `ibtRoutes`   | object   | Available IBT operations                          |
+
+#### Steps to Add a Token
+
+1. **Create Branch**
+
+    ```bash
+    git checkout -b chore/token-<SYMBOL>-<CHAIN_ID>
+    ```
+
+2. **Create Token Directory**
+
+    ```bash
+    mkdir -p src/tokens/<CHAIN_ID>/<ADDRESS>
+    ```
+
+3. **Add Token Metadata** (`src/tokens/<CHAIN_ID>/<ADDRESS>/index.json`)
+
+    ```json
+    {
+        "chainId": 1,
+        "address": "0x4104b135dbc9609fc1a9490e61369036497660c8",
+        "name": "Spectra",
+        "symbol": "SPECTRA",
+        "decimals": 18,
+        "logoURI": "/images/tokens/1/0x4104b135dbc9609fc1a9490e61369036497660c8.svg",
+        "extensions": {
+            "tags": [
+                "stable"
+            ]
+        }
+    }
+    ```
+
+4. **Add Token Logo** (`src/tokens/<CHAIN_ID>/<ADDRESS>/logo.{svg|png}`)
+
+    - Preferred format: SVG
+    - Alternative: High-quality PNG
+    - Recommended size: 64x64px minimum
+
+5. **Commit Changes**
+
+    ```bash
+    git add .
+    git commit -m "chore: add <SYMBOL>, chainId: <CHAIN_ID>"
+    ```
 
-## How to add a protocol
+6. **Create Pull Request**
+    - Title: `Add <SYMBOL> token (Chain: <CHAIN_ID>)`
+    - Include token details and verification links
 
-### Expected structure - `src/protocols/protocolList.json`
+### Adding ERC4626 Wrappers
 
-| ptAddress                                  | chainId | token.symbol | multipliers.amount | multipliers.name |
-| ------------------------------------------ | ------- | ------------ | ------------------ | ---------------- |
-| 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | 1       | weETH        | 1.5                | Karak XP         |
+**File Structure**: `src/wrappers/{chainId}/{address}/index.json`
 
-### Steps:
+ERC4626 wrappers follow the same structure as tokens but with additional vault-specific extensions.
 
-1. Create a new branch from the `main` with the name `chore/protocol-<protocol-name>-<chain-id>`
-2. Add the protocol to the `src/protocols/protocolList.json` file
+#### Required Extensions for Wrappers
 
-Example:
+| Field           | Type   | Description                |
+| --------------- | ------ | -------------------------- |
+| `vault`         | object | Vault contract information |
+| `vault.address` | string | Vault contract address     |
+| `vault.chainId` | number | Vault chain ID             |
+| `vault.name`    | string | Vault name                 |
+| `vault.symbol`  | string | Vault symbol               |
+
+#### Steps to Add a Wrapper
+
+1. **Create Branch**
+
+    ```bash
+    git checkout -b chore/wrapper-<SYMBOL>-<CHAIN_ID>
+    ```
+
+2. **Create Wrapper Directory**
+
+    ```bash
+    mkdir -p src/wrappers/<CHAIN_ID>/<ADDRESS>
+    ```
+
+3. **Add Wrapper Metadata** (`src/wrappers/<CHAIN_ID>/<ADDRESS>/index.json`)
+
+    ```json
+    {
+        "chainId": 1,
+        "address": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
+        "name": "Wrapped Ether",
+        "symbol": "KweETH",
+        "decimals": 18,
+        "logoURI": "/images/tokens/1/0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb.svg",
+        "extensions": {
+            "underlying": "0xa0b86a33e6c8a6a3f7c5d91c2e4f322b83c2c04e",
+            "vault": {
+                "chainId": 1,
+                "address": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
+                "name": "Wrapped Ether Vault",
+                "symbol": "KweETH",
+                "decimals": 18
+            },
+            "ibtRoutes": {
+                "deposit": true,
+                "mint": true,
+                "withdraw": true,
+                "redeem": true
+            }
+        }
+    }
+    ```
+
+4. **Commit and Submit**
+    ```bash
+    git commit -m "chore: add <SYMBOL> wrapper, chainId: <CHAIN_ID>"
+    ```
+
+### Adding Protocols
+
+**File**: `src/protocols/protocolList.json`
+
+Protocols define yield multipliers and reward configurations for principal tokens (PTs).
+
+#### Protocol Structure
+
+| Field         | Type         | Description                     |
+| ------------- | ------------ | ------------------------------- |
+| `ptAddress`   | string       | Principal token address         |
+| `chainId`     | number       | Network chain ID                |
+| `multipliers` | array/object | Reward multiplier configuration |
+
+#### Multiplier Types
+
+**Simple Multipliers** (array format):
 
 ```json
-[
-  ...
-  {
+{
     "ptAddress": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
     "chainId": 1,
     "multipliers": [
-      {
-        "amount": 1.5,
-        "name": "Karak XP"
-      },
-      {
-        "amount": 3,
-        "name": "Ether.fi Points"
-      },
-      {
-        "amount": 1,
-        "name": "EigenLayer Points"
-      }
+        {
+            "amount": 1.5,
+            "name": "Karak XP"
+        },
+        {
+            "amount": 3,
+            "name": "Ether.fi Points"
+        }
     ]
-  }
-]
+}
+```
+
+**Position-Specific Multipliers** (object format):
+
+```json
+{
+    "ptAddress": "0x5ca220f0f44e7bc76c2d1968c5d4fd5381432890",
+    "chainId": 1,
+    "multipliers": {
+        "lp": [
+            {
+                "amount": 2.5,
+                "name": "Yield Crumbs"
+            }
+        ],
+        "yt": [
+            {
+                "amount": 1,
+                "name": "Yield Crumbs"
+            }
+        ]
+    }
+}
 ```
 
-3. Commit the changes with the message: `chore: add <protocol-name>, chainId: <chain-id>`
-4. Create a pull request
-5. Once the PR is approved, the protocol will be added to the list and included in the Spectra platform in the next
-   build.
-6. Done
+#### Steps to Add a Protocol
+
+1. **Create Branch**
 
-## How to add a ERC4626 wrapper
+    ```bash
+    git checkout -b chore/protocol-<PROTOCOL_NAME>-<CHAIN_ID>
+    ```
+
+2. **Edit Protocol List** (`src/protocols/protocolList.json`)
+
+    ```json
+    [
+        {
+            "ptAddress": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
+            "chainId": 1,
+            "multipliers": [
+                {
+                    "amount": 1.5,
+                    "name": "Karak XP"
+                },
+                {
+                    "amount": 3,
+                    "name": "Ether.fi Points"
+                }
+            ]
+        }
+    ]
+    ```
 
-### Expected structure - `src/tokens/erc4626Wrappers.json`
+3. **Commit Changes**
+    ```bash
+    git commit -m "chore: add <PROTOCOL_NAME>, chainId: <CHAIN_ID>"
+    ```
 
-| chainId | address                                    | symbol | name          | decimals | logoURI                  | extensions                                          |
-| ------- | ------------------------------------------ | ------ | ------------- | -------- | ------------------------ | --------------------------------------------------- |
-| 1       | 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | KweETH | Wrapped Ether | 18       | /images/tokens/weETH.svg | underlying, ibtRoutes, protocol, aprEndpoint, vault |
+## 🔍 Schema Validation
 
-### Steps:
+All token data is validated against JSON schemas located in `src/schema/`:
 
-1. Create a new branch from the `main` with the name `chore/wrapper-<token-symbol>-<chain-id>`
-2. Add the wrapper to the `src/tokens/erc4626Wrappers.json` file
-3. Commit the changes with the message: `chore: add <token-symbol> wrapper, chainId: <chain-id>`
-4. Create a pull request
-5. Once the PR is approved, the wrapper will be added to the list and included in the Spectra platform in the next
-   build.
-6. Done
+-   `token.schema.json` - Token metadata validation
+-   `protocolList.schema.json` - Protocol configuration validation