@perspectivefi/token-list 1.26.0 → 1.26.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +262 -79
  2. package/dist/index.d.ts +2 -11
  3. package/dist/index.js +1 -13
  4. package/dist/index.js.map +1 -1
  5. package/package.json +3 -2
package/README.md CHANGED
@@ -1,113 +1,296 @@
1
1
  # Spectra Token List
2
2
 
3
- ## Overview
3
+ A comprehensive token registry for the Spectra Finance ecosystem, providing standardized metadata for tokens, ERC4626 wrappers and protocols across multiple networks.
4
4
 
5
- As Spectra, we use this repository as source of the tokens & platforms for our Web3 app as well as other services. This
6
- list is updated regularly as new tokens are added to the platform.
5
+ **App**: https://app.spectra.finance
6
+ **Package**: `@perspectivefi/token-list`
7
7
 
8
- #### Spectra App: https://app.spectra.finance
8
+ - [Installation](#installation)
9
+ - [Usage](#usage)
10
+ - [Data Structure](#data-structure)
11
+ - [Contributing](#contributing)
12
+ - [Adding Tokens](#adding-tokens)
13
+ - [Adding ERC4626 Wrappers](#adding-erc4626-wrappers)
14
+ - [Adding Protocols](#adding-protocols)
15
+ - [Schema Validation](#schema-validation)
16
+ - [Supported Networks](#supported-networks)
17
+ - [Development](#development)
9
18
 
10
- ## Tokens and Protocols
19
+ ## Installation
11
20
 
12
- - [Spectra Tokens](src/tokens/spectraTokens.json)
13
- - [Spectra ERC4626 Wrappers](src/tokens/erc4626Wrappers.json)
14
- - [Protocols](src/protocols/protocolList.json)
15
- - [Curators](src/curators/curatorList.json)
21
+ ```bash
22
+ npm install @perspectivefi/token-list
23
+ # or
24
+ yarn add @perspectivefi/token-list
25
+ ```
16
26
 
17
- ## How to add a token
27
+ ## Usage
18
28
 
19
- Expected structure - `src/tokens/spectraTokens.json`
29
+ ```typescript
30
+ import {
31
+ spectraTokens,
32
+ erc4626Wrappers,
33
+ protocolList,
34
+ } from "@perspectivefi/token-list"
35
+ ```
20
36
 
21
- | chainId | address | symbol | name | decimals | logoURI | extensions |
22
- | ------- | ------------------------------------------ | ------ | ------------- | -------- | ------------------------ | ----------------------------------------------------------- |
23
- | 1 | 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | KweETH | Wrapped Ether | 18 | /images/tokens/weETH.svg | underlying, ibtRoutes, protocol, faucetAddress, aprEndpoint |
37
+ ## Data Structure
24
38
 
25
- ### Steps:
39
+ ### Core Resources
26
40
 
27
- 1. Create a new branch from the `main` with the name `chore/token-<token-symbol>-<chain-id>`
28
- 2. Add the token to the `src/tokens/spectraTokens.json` file
41
+ | Resource | Description | Build Output |
42
+ | ------------- | ----------------------------------------------------------------------- | --------------------------------- |
43
+ | **Tokens** | Individual token metadata stored in `/src/tokens/{chainId}/{address}/` | `src/tokens/build.json` |
44
+ | **Wrappers** | ERC4626 wrapper metadata stored in `/src/wrappers/{chainId}/{address}/` | `src/wrappers/build.json` |
45
+ | **Protocols** | Protocol configurations and multipliers | `src/protocols/protocolList.json` |
29
46
 
30
- Example:
47
+ ### Token Structure
31
48
 
32
- ```json
33
- [
34
- ...
35
- {
36
- "chainId": 1,
37
- "address": "0x4104b135dbc9609fc1a9490e61369036497660c8",
38
- "name": "Spectra",
39
- "symbol": "APW",
40
- "decimals": 18,
41
- "logoURI": "images/tokens/apw.svg"
42
- }
43
- ]
49
+ Each token is stored as an individual directory containing:
50
+
51
+ ```
52
+ src/tokens/{chainId}/{address}/
53
+ ├── index.json # Token metadata
54
+ └── logo.{svg|png} # Token logo
44
55
  ```
45
56
 
46
- 3. Add the token logo to the `src/images/tokens` folder (use .png or .svg format)
47
- 4. Commit the changes with the message: `chore: add <token-symbol>, chainId: <chain-id>`
48
- 5. Create a pull request
49
- 6. Once the PR is approved, the token will be added to the list and included in the Spectra platform in the next build.
50
- 7. Done
57
+ ## Contributing
58
+
59
+ We welcome contributions! Please follow the guidelines below for adding new tokens, wrappers, or protocols.
60
+
61
+ ### Adding Tokens
62
+
63
+ **File Structure**: `src/tokens/{chainId}/{address}/index.json`
64
+
65
+ #### Required Fields
66
+
67
+ | Field | Type | Description | Example |
68
+ | ---------- | ------ | ------------------------- | ---------------------------------------------- |
69
+ | `chainId` | number | Network chain ID | `1` |
70
+ | `address` | string | Token contract address | `"0x4104b135dbc9609fc1a9490e61369036497660c8"` |
71
+ | `name` | string | Human-readable token name | `"Spectra"` |
72
+ | `symbol` | string | Token symbol | `"APW"` |
73
+ | `decimals` | number | Token decimals (1-18) | `18` |
74
+ | `logoURI` | string | Path to token logo | `"/images/tokens/1/0x4104...c8.svg"` |
75
+
76
+ #### Optional Extensions
77
+
78
+ | Field | Type | Description |
79
+ | ------------- | -------- | ------------------------------------------------- |
80
+ | `tags` | string[] | Token categories (`["stable", "liquid-staking"]`) |
81
+ | `underlying` | string | Underlying asset address |
82
+ | `protocol` | string | Associated protocol name |
83
+ | `aprEndpoint` | string | API endpoint for APR data |
84
+ | `ibtRoutes` | object | Available IBT operations |
85
+
86
+ #### Steps to Add a Token
87
+
88
+ 1. **Create Branch**
89
+
90
+ ```bash
91
+ git checkout -b chore/token-<SYMBOL>-<CHAIN_ID>
92
+ ```
93
+
94
+ 2. **Create Token Directory**
95
+
96
+ ```bash
97
+ mkdir -p src/tokens/<CHAIN_ID>/<ADDRESS>
98
+ ```
99
+
100
+ 3. **Add Token Metadata** (`src/tokens/<CHAIN_ID>/<ADDRESS>/index.json`)
101
+
102
+ ```json
103
+ {
104
+ "chainId": 1,
105
+ "address": "0x4104b135dbc9609fc1a9490e61369036497660c8",
106
+ "name": "Spectra",
107
+ "symbol": "SPECTRA",
108
+ "decimals": 18,
109
+ "logoURI": "/images/tokens/1/0x4104b135dbc9609fc1a9490e61369036497660c8.svg",
110
+ "extensions": {
111
+ "tags": [
112
+ "stable"
113
+ ]
114
+ }
115
+ }
116
+ ```
117
+
118
+ 4. **Add Token Logo** (`src/tokens/<CHAIN_ID>/<ADDRESS>/logo.{svg|png}`)
119
+
120
+ - Preferred format: SVG
121
+ - Alternative: High-quality PNG
122
+ - Recommended size: 64x64px minimum
123
+
124
+ 5. **Commit Changes**
125
+
126
+ ```bash
127
+ git add .
128
+ git commit -m "chore: add <SYMBOL>, chainId: <CHAIN_ID>"
129
+ ```
51
130
 
52
- ## How to add a protocol
131
+ 6. **Create Pull Request**
132
+ - Title: `Add <SYMBOL> token (Chain: <CHAIN_ID>)`
133
+ - Include token details and verification links
53
134
 
54
- ### Expected structure - `src/protocols/protocolList.json`
135
+ ### Adding ERC4626 Wrappers
55
136
 
56
- | ptAddress | chainId | token.symbol | multipliers.amount | multipliers.name |
57
- | ------------------------------------------ | ------- | ------------ | ------------------ | ---------------- |
58
- | 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | 1 | weETH | 1.5 | Karak XP |
137
+ **File Structure**: `src/wrappers/{chainId}/{address}/index.json`
59
138
 
60
- ### Steps:
139
+ ERC4626 wrappers follow the same structure as tokens but with additional vault-specific extensions.
61
140
 
62
- 1. Create a new branch from the `main` with the name `chore/protocol-<protocol-name>-<chain-id>`
63
- 2. Add the protocol to the `src/protocols/protocolList.json` file
141
+ #### Required Extensions for Wrappers
64
142
 
65
- Example:
143
+ | Field | Type | Description |
144
+ | --------------- | ------ | -------------------------- |
145
+ | `vault` | object | Vault contract information |
146
+ | `vault.address` | string | Vault contract address |
147
+ | `vault.chainId` | number | Vault chain ID |
148
+ | `vault.name` | string | Vault name |
149
+ | `vault.symbol` | string | Vault symbol |
150
+
151
+ #### Steps to Add a Wrapper
152
+
153
+ 1. **Create Branch**
154
+
155
+ ```bash
156
+ git checkout -b chore/wrapper-<SYMBOL>-<CHAIN_ID>
157
+ ```
158
+
159
+ 2. **Create Wrapper Directory**
160
+
161
+ ```bash
162
+ mkdir -p src/wrappers/<CHAIN_ID>/<ADDRESS>
163
+ ```
164
+
165
+ 3. **Add Wrapper Metadata** (`src/wrappers/<CHAIN_ID>/<ADDRESS>/index.json`)
166
+
167
+ ```json
168
+ {
169
+ "chainId": 1,
170
+ "address": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
171
+ "name": "Wrapped Ether",
172
+ "symbol": "KweETH",
173
+ "decimals": 18,
174
+ "logoURI": "/images/tokens/1/0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb.svg",
175
+ "extensions": {
176
+ "underlying": "0xa0b86a33e6c8a6a3f7c5d91c2e4f322b83c2c04e",
177
+ "vault": {
178
+ "chainId": 1,
179
+ "address": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
180
+ "name": "Wrapped Ether Vault",
181
+ "symbol": "KweETH",
182
+ "decimals": 18
183
+ },
184
+ "ibtRoutes": {
185
+ "deposit": true,
186
+ "mint": true,
187
+ "withdraw": true,
188
+ "redeem": true
189
+ }
190
+ }
191
+ }
192
+ ```
193
+
194
+ 4. **Commit and Submit**
195
+ ```bash
196
+ git commit -m "chore: add <SYMBOL> wrapper, chainId: <CHAIN_ID>"
197
+ ```
198
+
199
+ ### Adding Protocols
200
+
201
+ **File**: `src/protocols/protocolList.json`
202
+
203
+ Protocols define yield multipliers and reward configurations for principal tokens (PTs).
204
+
205
+ #### Protocol Structure
206
+
207
+ | Field | Type | Description |
208
+ | ------------- | ------------ | ------------------------------- |
209
+ | `ptAddress` | string | Principal token address |
210
+ | `chainId` | number | Network chain ID |
211
+ | `multipliers` | array/object | Reward multiplier configuration |
212
+
213
+ #### Multiplier Types
214
+
215
+ **Simple Multipliers** (array format):
66
216
 
67
217
  ```json
68
- [
69
- ...
70
- {
218
+ {
71
219
  "ptAddress": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
72
220
  "chainId": 1,
73
221
  "multipliers": [
74
- {
75
- "amount": 1.5,
76
- "name": "Karak XP"
77
- },
78
- {
79
- "amount": 3,
80
- "name": "Ether.fi Points"
81
- },
82
- {
83
- "amount": 1,
84
- "name": "EigenLayer Points"
85
- }
222
+ {
223
+ "amount": 1.5,
224
+ "name": "Karak XP"
225
+ },
226
+ {
227
+ "amount": 3,
228
+ "name": "Ether.fi Points"
229
+ }
86
230
  ]
87
- }
88
- ]
231
+ }
232
+ ```
233
+
234
+ **Position-Specific Multipliers** (object format):
235
+
236
+ ```json
237
+ {
238
+ "ptAddress": "0x5ca220f0f44e7bc76c2d1968c5d4fd5381432890",
239
+ "chainId": 1,
240
+ "multipliers": {
241
+ "lp": [
242
+ {
243
+ "amount": 2.5,
244
+ "name": "Yield Crumbs"
245
+ }
246
+ ],
247
+ "yt": [
248
+ {
249
+ "amount": 1,
250
+ "name": "Yield Crumbs"
251
+ }
252
+ ]
253
+ }
254
+ }
89
255
  ```
90
256
 
91
- 3. Commit the changes with the message: `chore: add <protocol-name>, chainId: <chain-id>`
92
- 4. Create a pull request
93
- 5. Once the PR is approved, the protocol will be added to the list and included in the Spectra platform in the next
94
- build.
95
- 6. Done
257
+ #### Steps to Add a Protocol
258
+
259
+ 1. **Create Branch**
96
260
 
97
- ## How to add a ERC4626 wrapper
261
+ ```bash
262
+ git checkout -b chore/protocol-<PROTOCOL_NAME>-<CHAIN_ID>
263
+ ```
264
+
265
+ 2. **Edit Protocol List** (`src/protocols/protocolList.json`)
266
+
267
+ ```json
268
+ [
269
+ {
270
+ "ptAddress": "0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb",
271
+ "chainId": 1,
272
+ "multipliers": [
273
+ {
274
+ "amount": 1.5,
275
+ "name": "Karak XP"
276
+ },
277
+ {
278
+ "amount": 3,
279
+ "name": "Ether.fi Points"
280
+ }
281
+ ]
282
+ }
283
+ ]
284
+ ```
98
285
 
99
- ### Expected structure - `src/tokens/erc4626Wrappers.json`
286
+ 3. **Commit Changes**
287
+ ```bash
288
+ git commit -m "chore: add <PROTOCOL_NAME>, chainId: <CHAIN_ID>"
289
+ ```
100
290
 
101
- | chainId | address | symbol | name | decimals | logoURI | extensions |
102
- | ------- | ------------------------------------------ | ------ | ------------- | -------- | ------------------------ | --------------------------------------------------- |
103
- | 1 | 0x6def54ae7e38992a7d1ab60d279483ba7f7b0aeb | KweETH | Wrapped Ether | 18 | /images/tokens/weETH.svg | underlying, ibtRoutes, protocol, aprEndpoint, vault |
291
+ ## 🔍 Schema Validation
104
292
 
105
- ### Steps:
293
+ All token data is validated against JSON schemas located in `src/schema/`:
106
294
 
107
- 1. Create a new branch from the `main` with the name `chore/wrapper-<token-symbol>-<chain-id>`
108
- 2. Add the wrapper to the `src/tokens/erc4626Wrappers.json` file
109
- 3. Commit the changes with the message: `chore: add <token-symbol> wrapper, chainId: <chain-id>`
110
- 4. Create a pull request
111
- 5. Once the PR is approved, the wrapper will be added to the list and included in the Spectra platform in the next
112
- build.
113
- 6. Done
295
+ - `token.schema.json` - Token metadata validation
296
+ - `protocolList.schema.json` - Protocol configuration validation
package/dist/index.d.ts CHANGED
@@ -1153,15 +1153,6 @@ var protocolList = [
1153
1153
  }
1154
1154
  ];
1155
1155
 
1156
- var curatorList = [
1157
- {
1158
- address: "0x3f2edd2AEaA3aF225D23b225bAf8CCEB900AF7d8",
1159
- name: "Test Curator",
1160
- website: "https://testcurator.com",
1161
- admin: "0x0000000000000000000000000000000000000000"
1162
- }
1163
- ];
1164
-
1165
1156
  var build$1 = [
1166
1157
  {
1167
1158
  address: "0x5b8ce6d591c914a56cb019b3decb63ede22708c8",
@@ -5296,7 +5287,7 @@ var build = [
5296
5287
  decimals: 18,
5297
5288
  logoURI: "/images/tokens/43114/0x14a84f1a61ccd7d1be596a6cc11fe33a36bc1646.svg",
5298
5289
  extensions: {
5299
- underlying: "0x5Ac32E4c756bD57630eAdF216668Ba16fA4635a2",
5290
+ underlying: "0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7",
5300
5291
  protocol: "Treehouse",
5301
5292
  externalLink: "https://app.treehouse.finance/vault/tavax",
5302
5293
  vault: {
@@ -6435,4 +6426,4 @@ var build = [
6435
6426
  }
6436
6427
  ];
6437
6428
 
6438
- export { curatorList, build as erc4626Wrappers, protocolList, build$1 as spectraTokens };
6429
+ export { build as erc4626Wrappers, protocolList, build$1 as spectraTokens };
package/dist/index.js CHANGED
@@ -19,7 +19,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
19
19
  // src/index.ts
20
20
  var src_exports = {};
21
21
  __export(src_exports, {
22
- curatorList: () => curatorList_default,
23
22
  erc4626Wrappers: () => build_default2,
24
23
  protocolList: () => protocolList_default,
25
24
  spectraTokens: () => build_default
@@ -1181,16 +1180,6 @@ var protocolList_default = [
1181
1180
  }
1182
1181
  ];
1183
1182
 
1184
- // src/curators/curatorList.json
1185
- var curatorList_default = [
1186
- {
1187
- address: "0x3f2edd2AEaA3aF225D23b225bAf8CCEB900AF7d8",
1188
- name: "Test Curator",
1189
- website: "https://testcurator.com",
1190
- admin: "0x0000000000000000000000000000000000000000"
1191
- }
1192
- ];
1193
-
1194
1183
  // src/tokens/build.json
1195
1184
  var build_default = [
1196
1185
  {
@@ -5327,7 +5316,7 @@ var build_default2 = [
5327
5316
  decimals: 18,
5328
5317
  logoURI: "/images/tokens/43114/0x14a84f1a61ccd7d1be596a6cc11fe33a36bc1646.svg",
5329
5318
  extensions: {
5330
- underlying: "0x5Ac32E4c756bD57630eAdF216668Ba16fA4635a2",
5319
+ underlying: "0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7",
5331
5320
  protocol: "Treehouse",
5332
5321
  externalLink: "https://app.treehouse.finance/vault/tavax",
5333
5322
  vault: {
@@ -6467,7 +6456,6 @@ var build_default2 = [
6467
6456
  ];
6468
6457
  // Annotate the CommonJS export names for ESM import in node:
6469
6458
  0 && (module.exports = {
6470
- curatorList,
6471
6459
  erc4626Wrappers,
6472
6460
  protocolList,
6473
6461
  spectraTokens