chore: modernize tooling, remove dead code, and rewrite docs

.env.example

@@ -3,4 +3,3 @@ PROVIDER_URL=https://mainnet.infura.io/v3/<YOUR_INFURA_API_KEY>
 LINEA_PROVIDER_URL=https://linea-mainnet.infura.io/v3/<YOUR_INFURA_API_KEY>
 CONTRACT_ADDRESS=0x051F1D88f0aF5763fB888eC4378b4D8B29ea3319
 L2_CONTRACT_ADDRESS=0x353012dc4a9A6cF55c941bADC267f82004A8ceB9
-COINMARKETCAP_API_KEY=<YOUR_COINMARKETCAP_API_KEY>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,13 +1,34 @@
+## Description
+
 **Action:** Add / Update / Remove token (choose one)
 
+**Token name:** <!-- e.g. USD Coin -->
+**Network:** Mainnet / Sepolia (choose one)
+
 **Context / Rationale:**
-<brief explanation here>
+
+<!-- Brief explanation of why this change is needed -->
+
+Closes #<!-- issue number, if applicable -->
 
 ---
 
-### PR Checklist
+## Type of Change
+
+- [ ] Token addition
+- [ ] Token update (metadata, address, type)
+- [ ] Token removal
+- [ ] Documentation update
+- [ ] Code change (scripts, config, CI)
+
+## Checklist
 
-- [ ] Verified and published the contract source
-- [ ] Kept the token list in alphabetical order by token symbol
+- [ ] Verified and published the contract source on an explorer
+- [ ] Kept the token list in alphabetical order by token name
 - [ ] Updated the `updatedAt` field (and `createdAt` if applicable)
-- [ ] Updated the list version number according to the README instructions
+- [ ] Updated the list version number according to the
+      [guidelines](./docs/development.md#guidelines)
+- [ ] JSON conforms to the
+      [schema](./json/schema/l2-token-list-schema.json)
+- [ ] Did not modify the schema or template files
+- [ ] No secrets, private keys, or real API keys in the diff

.github/workflows/validate-json.yml

@@ -16,10 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
           cache: 'npm'
@@ -28,7 +28,7 @@ jobs:
         run: npm ci
 
       - name: Run TypeScript check
-        run: npx tsc --noEmit
+        run: npm run typecheck
 
       - name: Run linter
         run: npm run lint
@@ -37,16 +37,16 @@ jobs:
         run: npm test
 
       - name: Check formatting
-        run: npm run prettify
+        run: npm run prettier
 
   validate_json:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

.github/workflows/verify-json.yml

@@ -18,12 +18,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
           cache: 'npm'

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm run lint && npm run precommit
+npm run lint && npm run prettier

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to Linea Token List
+
+Thank you for your interest in contributing to the Linea Token List. This guide covers
+the development workflow for maintainers and external contributors.
+
+## Prerequisites
+
+See the [Requirements](./README.md#requirements) section in the README.
+
+## Getting Started
+
+```bash
+git clone git@github.com:Consensys/linea-token-list.git
+cd linea-token-list
+cp .env.example .env
+npm install
+```
+
+## Development Workflow
+
+1. Create a feature branch from `main`:
+
+   ```bash
+   git checkout -b feat/add-token-xyz
+   ```
+
+2. Make your changes (see the [Development Guide](./docs/development.md) for token
+   addition procedures and guidelines).
+
+3. Run quality checks before committing:
+
+   ```bash
+   npm run lint
+   npm run prettier
+   npm test
+   ```
+
+   The pre-commit hook runs lint and formatting checks automatically.
+
+4. Commit your changes and push the branch:
+
+   ```bash
+   git add .
+   git commit -m "feat: add XYZ token to mainnet shortlist"
+   git push -u origin feat/add-token-xyz
+   ```
+
+5. Open a pull request against `main` on
+   [GitHub](https://github.com/Consensys/linea-token-list/pulls). Fill in the
+   [PR template](./.github/PULL_REQUEST_TEMPLATE.md).
+
+## Code Quality
+
+| Check             | Command                | Description                                     |
+| ----------------- | ---------------------- | ----------------------------------------------- |
+| Lint              | `npm run lint`         | ESLint checks on TypeScript source              |
+| Lint (auto-fix)   | `npm run lint:fix`     | Auto-fix lint errors                            |
+| Format            | `npm run prettier`     | Prettier formatting check                       |
+| Format (auto-fix) | `npm run prettier:fix` | Auto-fix formatting                             |
+| Tests             | `npm test`             | Jest unit tests                                 |
+| Verify            | `npm run verify`       | Full on-chain verification of mainnet shortlist |
+
+## PR Guidelines
+
+- Use the [PR template](./.github/PULL_REQUEST_TEMPLATE.md).
+- Only commit the token list file(s). Do not modify the schema or templates.
+- Ensure CI checks pass before requesting review.
+- Keep one token addition per PR unless batch additions are coordinated with maintainers.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same
+[MIT OR Apache-2.0](./README.md#license) dual license as the project.

README.md

@@ -1,25 +1,126 @@
 # Linea Token List
 
-This repository maintains lists of ERC20 tokens available on Linea. There are two lists: one for Linea Mainnet and one
-for Linea Sepolia. It is manually curated by our team, and updated based on submitted PRs via
+Curated lists of ERC-20 tokens available on Linea Mainnet and Linea Sepolia, used by
+the [Linea canonical bridge](https://bridge.linea.build/) UI.
+
+The lists are manually curated by the Linea team and updated based on submitted PRs via
 the [Linea Developer Hub](https://developer.linea.build).
 
-If you want to add a token or validate an addition, please follow the procedures outlined below.
+## Requirements
+
+- [Node.js](https://nodejs.org/) v22.22.0 (see [`.nvmrc`](./.nvmrc))
+- [npm](https://docs.npmjs.com/) v10.0.0+ (ships with Node.js; pinned to `10.9.2` via `packageManager`)
+
+## Getting Started
+
+```bash
+cp .env.example .env   # configure optional provider URLs
+npm install
+npm test               # run the unit-test suite
+```
+
+## Development
+
+See the full [Development Guide](./docs/development.md) for setup details, token addition
+procedures, and guidelines.
+
+### Common Commands
+
+| Command                | Description                                                            |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `npm test`             | Run the unit-test suite (Jest)                                         |
+| `npm run lint`         | Check for lint errors (ESLint)                                         |
+| `npm run lint:fix`     | Auto-fix lint errors                                                   |
+| `npm run prettier`     | Check formatting (Prettier)                                            |
+| `npm run prettier:fix` | Auto-fix formatting                                                    |
+| `npm run verify`       | Compile TypeScript, verify mainnet shortlist on-chain, and auto-format |
+
+### Examples
+
+```bash
+# Verify the mainnet token list against on-chain data
+npm run verify
+
+# Lint and format in one shot
+npm run lint:fix && npm run prettier:fix
+```
+
+## Project Structure
 
-## Add a token to the shortlist
+```text
+linea-token-list/
+├── .github/
+│   ├── workflows/          # CI/CD workflow definitions
+│   └── PULL_REQUEST_TEMPLATE.md
+├── docs/
+│   └── development.md      # Development guide and token-addition procedures
+├── json/
+│   ├── linea-mainnet-token-shortlist.json
+│   ├── linea-sepolia-token-shortlist.json
+│   ├── schema/
+│   │   └── l2-token-list-schema.json
+│   └── templates/
+│       └── linea-sepolia-token-version-template.json
+├── src/
+│   ├── abis/               # ABI files (ERC-20, token bridge)
+│   ├── config/             # App configuration and Joi schema
+│   ├── logger/             # Winston logger setup
+│   ├── models/             # TypeScript type definitions
+│   ├── services/           # Core token verification service
+│   └── utils/              # Helpers (validation, file I/O, Ethereum utils)
+├── scripts/
+│   └── verifyMainnetShortlist.ts  # Entry point for `npm run verify`
+├── .env.example            # Environment variable template
+├── eslint.config.js        # ESLint flat config
+├── jest.config.js          # Jest configuration
+├── tsconfig.json           # TypeScript configuration
+└── package.json
+```
 
-If you represent a project with a token on Linea, it's beneficial to add it to the shortlist. Tokens on this list are
-reflected in the UI of the Linea canonical bridge.
+**Key tooling:**
 
-> [!IMPORTANT]
-> Before adding a new token, you must verify the token's smart contract on an explorer. This ensures the authenticity
-> and security of the token. You can verify the smart contract
-> through [LineaScan](https://lineascan.build/verifyContract)
+- **Package manager**: npm (strict engine enforcement via `.npmrc`)
+- **Linting**: ESLint with `typescript-eslint`
+- **Formatting**: Prettier
+- **Testing**: Jest with `ts-jest`
+- **Git hooks**: Husky (pre-commit runs lint + format check)
+
+## CI/CD
+
+### Continuous Integration
+
+| Workflow                                                               | Trigger                       | Description                                                       |
+| ---------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| [Test and Validate JSON](./.github/workflows/validate-json.yml)        | Push to `main`, PRs to `main` | TypeScript check, lint, tests, formatting, JSON schema validation |
+| [Security Code Scanner](./.github/workflows/security-code-scanner.yml) | Push to `main`, PRs to `main` | MetaMask security code scanner                                    |
+
+### Continuous Verification
+
+| Workflow                                           | Trigger        | Description                                      |
+| -------------------------------------------------- | -------------- | ------------------------------------------------ |
+| [Verify JSON](./.github/workflows/verify-json.yml) | Push to `main` | Verifies mainnet shortlist against on-chain data |
+
+## Add a Token to the Shortlist
+
+If you represent a project with a token on Linea, it is beneficial to add it to the
+shortlist. Tokens on this list are reflected in the UI of the Linea canonical bridge.
+
+> **Important:** Before adding a new token, you must verify the token's smart contract on
+> an explorer. This ensures the authenticity and security of the token. You can verify the
+> smart contract through [LineaScan](https://lineascan.build/verifyContract)
 > or [other tools](https://docs.linea.build/get-started/how-to/verify-smart-contract).
 > The same verification should be done on Ethereum L1 and Linea if necessary.
 
-To add a new token, you need to go through the [Linea Developer Hub](https://developer.linea.build) registration process.
+To add a new token, go through the [Linea Developer Hub](https://developer.linea.build)
+registration process.
+
+For maintainers who need to add a token manually, see the
+[Development Guide](./docs/development.md#manually-add-a-token-to-the-list).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-## Technical resources (for maintainers)
+## License
 
-- [Development Guide](./docs/development.md).
+Dual-licensed under [MIT](./LICENSE-MIT) or [Apache-2.0](./LICENSE-APACHE).