Merge pull request #3 from minswap/tlinh

Fix to support old apis, refactor and update README.md

README.md

@@ -1,11 +1,37 @@
-# Minswap tokens
+# 😽 Minswap tokens
+
+## Overview
+
 The merge of deprecated verified-tokens and market cap repositories, which contains a list of tokens, exposes APIs for transparent access to circulating supply and total supply.
 
-## Requirements
-For tokens to be verified, ensure your token has a pool with at least **1000 ADA TVL** and follow the structures stated in the instructions below. Any token that has been verified does not meet the requirements in the future would still be unverified.
+As of latest update, we consider `circulating = maxSupply - treasury - burn` and `total = maxSupply - burn` as standard formulas for calculating marketcap information.
+
+In cases where `circulatingOnChain` is provided directly according to the asset's quantity on-chain or through external APIs, the `circulating` is the value of `circulatingOnChain`.
+
+For tokens providing with `treasuryNft`, the `circulating` is the quantity of the address containing the assets. In default, the amount is retrieved from the oldest address from the blockchain's point of view.
 
 ## How to add my token
-Create a pull request adding yaml file according to the following structure in the `src/tokens`:
+### Requirements
+As token verification prerequisites, ensure your token has:
+- A pool with at least **1000 ADA TVL**
+- A logo added in the [Cardano Token Registry](https://github.com/cardano-foundation/cardano-token-registry) or CIP-68 metadata
+and follow the structure stated in the instructions below.
+- A post of your policy ID on Twitter or your policy ID displayed on your landing page.
+
+For tokens to be verified:
+1. Create a transaction transfer **100 ADA** to Minswap wallet receiving token verification fee below. This fee appears as the cost for lifetime maintain this repository.
+2. Metadata includes: **the last 4 numbers of asset's policyId and asset's ticker** (for example, Verify 70c6 MIN).
+3. Attach the transaction hash to a comment in the yaml file pull request (instructions below).
+
+
+Minswap wallet receiving token verification fee: `addr1q85g6fkwzr2cf984qdmntqthl3yxnw4pst4mpgeyygdlnehqlcgwvr6c9vmajz96vnmmset3earqt5wl0keg0kw60eysdgwnej`
+
+Any token that has been verified does not meet the requirements in the future would still be unverified.
+
+### Create pull request
+
+1. Create a pull request adding yaml file according to the following structure in the `src/tokens`:
+
 ```yaml
 # 1 token = 1 yaml file
 # filename/assetId: policyId + hex-coded token name
@@ -46,4 +72,41 @@ circulatingOnChain:
   - stake...
   - https://...
   - assetId
+
+treasuryNft: assetId
+```
+
+Alternatively, create an issue with above information and our team will update accordingly. The pull request will be processed faster.
+Our team will verify and approve in first-in-first-out order.
+
+## Usage
+
+```ts
+import {
+  BlockFrostAdapter,
+  MarketCapAPI,
+  TokenAPI,
+} from "@minswap/minswap-tokens";
+
+const MIN_TOKEN =
+  "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e";
+
+// getting token info
+const tokenApi = new TokenAPI();
+
+const minTokenInfo = await tokenApi.getToken(MIN_TOKEN);
+
+console.log(minTokenInfo);
+
+// getting Market Cap info
+const blockFrostAdapter = new BlockFrostAdapter({
+  projectId: "<your_project_id_here>",
+  requestTimeout: 20_000,
+});
+
+const marketCapApi = new MarketCapAPI(blockFrostAdapter);
+
+const minMarketCapInfo = await marketCapApi.getMarketCapInfo(minTokenInfo);
+console.log(minMarketCapInfo);
+// { circulating: '240813714.66121483', total: '5000000000' }
 ```

biome.json

@@ -6,7 +6,7 @@
   },
   "files": {
     "ignoreUnknown": false,
-    "ignore": ["node_modules/**", ".vscode/**", ".husky", "build", "src/tokens", "*.config.js"]
+    "ignore": ["node_modules/**", ".vscode/**", ".husky", "build", "src/tokens", "*.config.js", "package.json"]
   },
   "formatter": {
     "bracketSpacing": true,

internal/checkTVL.ts

@@ -32,7 +32,7 @@ const blockfrostAdapter = new SDK.BlockfrostAdapter({
 async function verifyTVL() {
   const [v1Pools, { pools: v2Pools }] = await Promise.all([getAllV1Pools(), blockfrostAdapter.getAllV2Pools()]);
 
-  fs.readdir(TOKEN_DIR, async function (error, files) {
+  fs.readdir(TOKEN_DIR, async (error, files) => {
     if (error) {
       throw error;
     }
@@ -44,7 +44,9 @@ async function verifyTVL() {
       if (newVerified === tokenData.verified) {
         continue;
       }
-
+      console.log(
+        `TVL check failed, changing verification information from ${tokenData.verified} to ${newVerified}...`,
+      );
       const tokenInfo = {
         ...tokenData,
         verified: newVerified,
@@ -85,6 +87,7 @@ async function getAllV1Pools() {
 
   let page = 1;
   while (true) {
+    console.log(`Fetching V1 Pools on page: ${page}...`);
     const paginatedPools = await blockfrostAdapter.getV1Pools({
       page,
       count: LIMIT_PAGINATION,

internal/validateTokenFiles.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import Ajv from "ajv";
 import { load } from "js-yaml";
 
-import { TOKENS_DIR } from "../src/consts";
+import { ASSET_ID_REGEX, TOKENS_DIR } from "../src/consts";
 import { tokenSchema } from "../src/tokenSchema";
 import type { TokenMetadata } from "../src/types";
 
@@ -18,6 +18,10 @@ async function validateTokenFiles() {
       throw error;
     }
     for (const file of files) {
+      const fileName = file.split(".")[0];
+      if (!fileName.match(ASSET_ID_REGEX)) {
+        throw new Error(`Invalid filename: ${fileName}`);
+      }
       const filePath = path.join(TOKEN_DIR, `${file}`);
       const tokenFileData = fs.readFileSync(filePath, "utf-8");
       const tokenData: TokenMetadata = {
@@ -26,7 +30,7 @@ async function validateTokenFiles() {
       };
       const validate = ajv.validate(tokenSchema, tokenData);
       if (!validate) {
-        throw new Error(`Error validating token, token file: ${file}`);
+        throw new Error(`Validating failed token file: ${file}`);
       }
     }
   });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minswap/minswap-tokens",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "The merge of deprecated verified-tokens and market-cap repositories, which contains a list of tokens, exposes APIs for transparent access to circulating supply and total supply.",
   "main": "build/index.js",
   "module": "build/index.es.js",
@@ -16,17 +16,27 @@
     "prepare": "husky install"
   },
   "lint-staged": {
-    "*": ["pnpm lint", "pnpm check-format"]
+    "*": [
+      "pnpm lint",
+      "pnpm check-format"
+    ]
   },
-  "files": ["build"],
+  "files": [
+    "build"
+  ],
   "exports": {
     ".": {
       "types": "./build/index.d.ts",
       "import": "./build/index.es.js",
       "require": "./build/index.js"
     }
   },
-  "keywords": ["minswap", "cardano", "dex", "blockchain"],
+  "keywords": [
+    "minswap",
+    "cardano",
+    "dex",
+    "blockchain"
+  ],
   "author": "Minswap Labs",
   "license": "ISC",
   "repository": {

src/adapters/types.ts

@@ -18,8 +18,7 @@ export type Adapter = {
 
   /**
    * Get the amount held in the address holding a specific asset by the asset's ID.
-   * After obtaining a list of addresses possessing a specific asset in descending order,
-   * this retrieve the amount associated with the first address returned.
+   * After obtaining a list of addresses possessing a specific asset in blockchain's point of view ascending order, this retrieve the amount associated with the first address returned.
    * This function currently supports Shen and DJED.
    * @param tokenId The token's policy ID.
    * @param nftId The concatenation of token's policy ID and hex-coded token name.