{"_id":"@covalenthq/goldrush-enhanced-spam-lists","_rev":"3-f1164385c2bac3e99219aacc6f5c390c","name":"@covalenthq/goldrush-enhanced-spam-lists","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@covalenthq/goldrush-enhanced-spam-lists","version":"0.0.1","keywords":["spam","erc20","nft","crypto","tokens"],"author":{"name":"covalenthq"},"license":"MIT","_id":"@covalenthq/goldrush-enhanced-spam-lists@0.0.1","maintainers":[{"name":"covalenthq_devops","email":"devops@covalenthq.com"},{"name":"harishraisinghani","email":"harishraisinghani@gmail.com"},{"name":"jagnani73","email":"yashjagnani73@gmail.com"}],"homepage":"https://goldrush.dev/docs/resources/enhanced-spam-lists","bugs":{"url":"https://github.com/covalenthq/goldrush-enhanced-spam-lists/issues"},"dist":{"shasum":"53ce33d0b0b4c91b06bdd382bfe4a835a4368320","tarball":"https://registry.npmjs.org/@covalenthq/goldrush-enhanced-spam-lists/-/goldrush-enhanced-spam-lists-0.0.1.tgz","fileCount":7,"integrity":"sha512-s7/CyhpmQlWwx36i8TBGocfzb+rzpKMPNqVIN1N1p72sHLGthIkwYmQUTfZsOSZukBb+RwW74qpZYGMWaDoW+g==","signatures":[{"sig":"MEUCIQDeLn0fQqeKgszXIpIbeRIGABMECGft4BCL04uSbVW8cAIgIc7EyHJFrU8S2baXdYkcjf+v0tyIYOustJTHjt0qF3Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24516},"main":"dist/index.js","type":"module","_from":"file:covalenthq-goldrush-enhanced-spam-lists-0.0.1.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"lint":"eslint .","test":"vitest run --config vitest.config.ts","build":"pnpm run clean && tsc","clean":"rimraf dist","pretty":"prettier . --write"},"_npmUser":{"name":"jagnani73","email":"yashjagnani73@gmail.com"},"_resolved":"C:\\Users\\YASHVA~1\\AppData\\Local\\Temp\\928f97e889c7833efaa5809aef2e1931\\covalenthq-goldrush-enhanced-spam-lists-0.0.1.tgz","_integrity":"sha512-s7/CyhpmQlWwx36i8TBGocfzb+rzpKMPNqVIN1N1p72sHLGthIkwYmQUTfZsOSZukBb+RwW74qpZYGMWaDoW+g==","repository":{"url":"git+https://github.com/covalenthq/goldrush-enhanced-spam-lists.git","type":"git"},"_npmVersion":"10.2.3","description":"Multi-chain enhanced spam token lists for ERC20 & NFT contracts","directories":{},"_nodeVersion":"20.10.0","dependencies":{"js-yaml":"^4.1.0","isomorphic-fetch":"^3.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.21.0","rimraf":"^6.0.1","vitest":"^3.0.9","prettier":"^3.5.3","@eslint/js":"^9.21.0","typescript":"5.7.3","@types/node":"^22.13.8","@types/js-yaml":"^4.0.9","@eslint/eslintrc":"^3.3.0","@vitest/coverage-v8":"^3.0.9","eslint-config-prettier":"^10.0.2","eslint-plugin-prettier":"^5.2.3","@types/isomorphic-fetch":"^0.0.39","@typescript-eslint/parser":"^8.25.0","@typescript-eslint/eslint-plugin":"^8.25.0","@trivago/prettier-plugin-sort-imports":"^5.2.2"},"_npmOperationalInternal":{"tmp":"tmp/goldrush-enhanced-spam-lists_0.0.1_1743109812066_0.7392885854491835","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-03-27T21:10:12.008Z","modified":"2026-09-30T04:30:27.123Z","0.0.1":"2025-03-27T21:10:12.262Z"},"bugs":{"url":"https://github.com/covalenthq/goldrush-enhanced-spam-lists/issues"},"author":{"name":"covalenthq"},"license":"MIT","homepage":"https://goldrush.dev/docs/resources/enhanced-spam-lists","keywords":["spam","erc20","nft","crypto","tokens"],"repository":{"url":"git+https://github.com/covalenthq/goldrush-enhanced-spam-lists.git","type":"git"},"description":"Multi-chain enhanced spam token lists for ERC20 & NFT contracts","maintainers":[{"email":"devops@covalenthq.com","name":"covalenthq_devops"}],"readme":"<div align=\"center\">\r\n  \r\n# GoldRush Enhanced Spam Lists\r\n\r\n[![NPM Version](https://img.shields.io/npm/v/@covalenthq/goldrush-enhanced-spam-lists)](https://www.npmjs.com/package/@covalenthq/goldrush-enhanced-spam-lists)\r\n[![NPM Downloads](https://img.shields.io/npm/dt/@covalenthq/goldrush-enhanced-spam-lists)](https://www.npmjs.com/package/@covalenthq/goldrush-enhanced-spam-lists)\r\n[![GitHub license](https://img.shields.io/github/license/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/blob/main/LICENSE)\r\n[![GitHub last commit](https://img.shields.io/github/last-commit/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/commits/master)\r\n[![GitHub contributors](https://img.shields.io/github/contributors/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/graphs/contributors)\r\n[![GitHub issues](https://img.shields.io/github/issues/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/issues)\r\n[![GitHub pull requests](https://img.shields.io/github/issues-pr/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/pulls)\r\n\r\n[![GitHub stars](https://img.shields.io/github/stars/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/stargazers)\r\n[![GitHub forks](https://img.shields.io/github/forks/covalenthq/goldrush-enhanced-spam-lists)](https://github.com/covalenthq/goldrush-enhanced-spam-lists/network/members)\r\n\r\n[📖 Documentation](https://goldrush.dev/docs/resources/enhanced-spam-lists)\r\n\r\n</div>\r\n\r\n`@covalenthq/goldrush-enhanced-spam-lists` is a public, open-source npm package that provides enhanced spam lists for ERC20 tokens and NFTs. Our mission is to restore trust and transparency in Web3 by helping developers, explorers, wallets, and indexers protect their users from scam tokens and malicious contracts.\r\n\r\n---\r\n\r\n## Overview\r\n\r\nIn response to the growing problem of spam in the crypto ecosystem, GoldRush is proud to launch the first-ever multichain enhanced spam token lists for ERC20 tokens and NFTs. This package initially supports the following six [Foundational Chains](https://goldrush.dev/chains/):\r\n\r\n- Ethereum Mainnet\r\n- Base Mainnet\r\n- Polygon Mainnet\r\n- BNB Smart Chain (BSC) Mainnet\r\n- Optimism Mainnet\r\n- Gnosis Mainnet\r\n\r\nThere are plans to extend the chain support. These enhanced spam token lists are currently **updated weekly.**\r\n\r\n### Key Features\r\n\r\n- Multichain support.\r\n- Dedicated ERC20 and NFT spam lists.\r\n- Enhanced classification for ERC20 tokens:\r\n    - `yes`: token contracts confirmed as spam (spam score > 20).\r\n    - `maybe`: token contracts that are potentially spam (12 < spam score < 20).\r\n- Each entry includes a `spam_score` to indicate the level of risk. Higher score indicates a higher spam risk.\r\n- Updated weekly.\r\n- Open source and collaborative.\r\n\r\n---\r\n\r\n## File Structure\r\n\r\nThe package organizes YAML files as follows:\r\n\r\n```\r\n/\r\n└── src/\r\n    └── lists/\r\n        ├── erc20/\r\n        │   ├── eth_mainnet_token_spam_contracts_yes.yaml\r\n        │   ├── eth_mainnet_token_spam_contracts_maybe.yaml\r\n        │   ├── base_mainnet_token_spam_contracts_yes.yaml\r\n        │   ├── base_mainnet_token_spam_contracts_maybe.yaml\r\n        │   ├── pol_mainnet_token_spam_contracts_yes.yaml\r\n        │   ├── pol_mainnet_token_spam_contracts_maybe.yaml\r\n        │   ├── op_mainnet_token_spam_contracts_yes.yaml\r\n        │   ├── op_mainnet_token_spam_contracts_maybe.yaml\r\n        │   ├── bsc_mainnet_token_spam_contracts_yes_1.yaml\r\n        │   ├── bsc_mainnet_token_spam_contracts_yes_2.yaml\r\n        │   ├── bsc_mainnet_token_spam_contracts_maybe.yaml\r\n        │   ├── gnosis_mainnet_token_spam_contracts_yes.yaml\r\n        │   └── gnosis_mainnet_token_spam_contracts_maybe.yaml\r\n        └── nft/\r\n            ├── eth_mainnet_nft_spam_contracts.yaml\r\n            ├── base_mainnet_nft_spam_contracts.yaml\r\n            ├── pol_mainnet_nft_spam_contracts.yaml\r\n            ├── op_mainnet_nft_spam_contracts.yaml\r\n            ├── bsc_mainnet_nft_spam_contracts.yaml\r\n            └── gnosis_mainnet_nft_spam_contracts.yaml\r\n```\r\n\r\n- **ERC20 Tokens:**\r\n    - Each chain has two YAML files:\r\n        - `<chain>_token_spam_contracts_yes.yaml` for token contracts confirmed as spam.\r\n        - `<chain>_token_spam_contracts_maybe.yaml` for token contracts that are potentially spam.\r\n- **NFTs:**\r\n    - Each chain has a single YAML file (e.g., `<chain>_nft_spam_contracts.yaml`) listing all NFT spam contracts.\r\n\r\n---\r\n\r\n## YAML File Formats\r\n\r\n### ERC20 YAML File Example\r\n\r\n```yaml\r\n---\r\nSpamContracts:\r\n    - 56/0x00107060f34b437c5a7daf6c247e6329cf613759/20\r\n    - 56/0x00518f36d2e0e514e8eb94d34124fc18ee756f10/85\r\n    - 56/0x00757bb08d0367a44be44f9b79c06e6775f733c5/70\r\n    - 56/0x00b09b2d87f88ebfa214fd247be08b1c4c1e5484/18\r\n```\r\n\r\n- **Key:** `SpamContracts` lists ERC20 spam contracts.\r\n- **Format:** Each contract entry uses the `<chainid>/<contract_address>/<spam_score>` format.\r\n\r\n### NFT YAML File Example\r\n\r\nEach NFT YAML file is dedicated to a specific chain. Every contract listed is considered spam. The file follows this format:\r\n\r\n```yaml\r\n---\r\nSpamContracts:\r\n    - 100/0x1043868cdc29037cce4ce3e495e601572e2cd78e/80\r\n    - 100/0x642f6eeab36134bbe6fbaab1eeb2a7ebc85739a8/55\r\n    - 100/0x616b02df3e80cec9a5dd764459141b85a91ffba4/30\r\n```\r\n\r\n- **Key:** `SpamContracts` lists all NFT spam contracts.\r\n- **Format:** Each entry uses the `<chainid>/<contract_address>/<spam_score>` format.\r\n\r\n---\r\n\r\n## Getting Started\r\n\r\n### Installation\r\n\r\nInstall the package using your preferred package manager:\r\n\r\n```bash\r\n# npm\r\nnpm install @covalenthq/goldrush-enhanced-spam-lists\r\n\r\n# yarn\r\nyarn add @covalenthq/goldrush-enhanced-spam-lists\r\n\r\n# pnpm\r\npnpm add @covalenthq/goldrush-enhanced-spam-lists\r\n```\r\n\r\n### Usage\r\n\r\n1. Verify if an ERC20 token is spam on a given network\r\n\r\n    ```javascript\r\n    import {\r\n        Networks,\r\n        isERC20Spam,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    // With default options\r\n    const isSpam = await isERC20Spam(\r\n        \"0xTokenAddress\",\r\n        Networks.ETHEREUM_MAINNET\r\n    );\r\n    console.log(isSpam);\r\n    ```\r\n\r\n2. For a potential spam check for an ERC20 token, `Confidence.MAYBE` can be used\r\n\r\n    ```javascript\r\n    import {\r\n        Confidence,\r\n        Networks,\r\n        isERC20Spam,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    const isPotentialSpam = await isERC20Spam(\r\n        \"0xTokenAddress\",\r\n        Networks.POLYGON_MAINNET,\r\n        Confidence.MAYBE\r\n    );\r\n    console.log(isPotentialSpam);\r\n    ```\r\n\r\n3. Verify if an NFT token is spam on a given network\r\n\r\n    ```javascript\r\n    import {\r\n        Networks,\r\n        isNFTSpam,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    const isNftSpam = await isNFTSpam(\"0xNftAddress\", Networks.BSC_MAINNET);\r\n    console.log(isNftSpam);\r\n    ```\r\n\r\n4. Control caching behavior\r\n\r\n    ```javascript\r\n    import {\r\n        Networks,\r\n        Confidence,\r\n        isERC20Spam,\r\n        clearCache,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    // With caching enabled (default)\r\n    const withCache = await isERC20Spam(\r\n        \"0xTokenAddress\",\r\n        Networks.ETHEREUM_MAINNET,\r\n        Confidence.YES,\r\n        true // Enable caching (default)\r\n    );\r\n\r\n    // Without caching (always fetches fresh data)\r\n    const withoutCache = await isERC20Spam(\r\n        \"0xTokenAddress\",\r\n        Networks.ETHEREUM_MAINNET,\r\n        Confidence.YES,\r\n        false // Disable caching\r\n    );\r\n\r\n    // Clear memory and disk cache if needed\r\n    clearCache();\r\n    ```\r\n\r\n5. For more control, you can get the full lists:\r\n\r\n    ```javascript\r\n    import {\r\n        getERC20List,\r\n        getNFTList,\r\n        Confidence,\r\n        Networks,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    // Get ERC20 spam list with default caching\r\n    const ethSpamTokens = await getERC20List(\r\n        Networks.ETHEREUM_MAINNET,\r\n        Confidence.YES\r\n    );\r\n\r\n    // Get NFT spam list with caching disabled\r\n    const bscSpamNfts = await getNFTList(Networks.BSC_MAINNET, false);\r\n    ```\r\n\r\n6. Get the specific spam score for a given contract\r\n\r\n    ```javascript\r\n    import {\r\n        getERC20List,\r\n        getSpamScore,\r\n        Networks,\r\n        Confidence,\r\n    } from \"@covalenthq/goldrush-enhanced-spam-lists\";\r\n\r\n    const ethSpamTokens = await getERC20List(\r\n        Networks.ETHEREUM_MAINNET,\r\n        Confidence.YES\r\n    );\r\n    const score = getSpamScore(ethSpamTokens[0]);\r\n    console.log(score); // Returns the spam score as a string\r\n    ```\r\n\r\n### Caching\r\n\r\nThis package uses a two-level caching system to improve performance:\r\n\r\n1. **In-memory cache**: Keeps data in memory during the lifetime of your application\r\n2. **Disk cache**: Stores data on disk in the system's temporary directory\r\n\r\nAll functions that fetch data accept an optional `cache` parameter (defaults to `true`):\r\n\r\n- `true`: Use both in-memory and disk caching (default)\r\n- `false`: Bypass all caching and always fetch fresh data from the source\r\n\r\nYou can clear both caches at any time with the `clearCache()` function.\r\n\r\n<br>\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions from the community! If you have suggestions, improvements, or new spam contract addresses to add, please open an issue or submit a pull request. Feel free to check <a href=\"https://github.com/covalenthq/goldrush-enhanced-spam-lists/issues\">issues</a> page.\r\n\r\n## Show your support\r\n\r\nGive a ⭐️ if this project helped you!\r\n\r\n## 📝 License\r\n\r\nThis project is <a href=\"https://github.com/covalenthq/goldrush-enhanced-spam-lists/blob/main/LICENSE\">MIT</a> licensed.\r\n\r\n_Cleaning up crypto, one spam token at a time._\r\n","readmeFilename":"README.md"}