@avaprotocol/protocols 0.2.0 → 0.3.0

package/README.md

@@ -149,6 +149,85 @@ There's no equivalent multi-protocol + multi-chain + addresses + ABIs + topics p
 
 Address verification: link to the canonical source (Etherscan-verified deployment, protocol docs, official address book). PRs that don't cite a source for the addresses won't merge.
 
+## Tokens sidecar (for non-TS consumers)
+
+`yarn build` writes a per-chain JSON file under `dist/tokens/` alongside the JS + d.ts outputs:
+
+```
+dist/tokens/
+├── ethereum.json       (chain 1)
+├── sepolia.json        (chain 11155111)
+├── base.json           (chain 8453)
+├── base-sepolia.json   (chain 84532)
+├── bnb-mainnet.json    (chain 56)
+└── holesky.json        (chain 17000)
+```
+
+Each file is a stable-sorted array of `{ id, name, symbol, decimals }` entries — the same schema the EigenLayer-AVS Go aggregator already consumes under `token_whitelist/*.json`, so a Go service can pick up the catalog without depending on the TS toolchain. `id` is the lowercased address (matching Go's read-side normalization). Metadata fields TS consumers use (`description`, `website`, `logoUrl`, `links`) are intentionally omitted; TS callers import the `Tokens` namespace from source instead.
+
+### When to run it
+
+- **Automatically** — `yarn build` invokes `yarn build:tokens-sidecar` as its last step, so any release publishes a fresh sidecar in the npm tarball.
+- **Standalone** — `yarn build:tokens-sidecar` when you've edited `src/tokens/` and want to inspect the generated JSON without rebuilding declarations + JS.
+
+### Adding a new chain
+
+The script throws fast if the catalog grows a token on a chain that isn't registered in `CHAIN_FILE_NAMES` inside `scripts/build-tokens-sidecar.ts`:
+
+```
+[tokens-sidecar] no file name registered for chain <id>.
+Add it to CHAIN_FILE_NAMES in scripts/build-tokens-sidecar.ts.
+```
+
+Fix is one line — append `[Chains.NewChain]: "newchain-mainnet"` to the map. The error message points at the exact file so this can't silently ship an incomplete sidecar.
+
+### Consuming the sidecar (Go example)
+
+```go
+// EigenLayer-AVS already does this for its checked-in
+// token_whitelist/*.json; the dist/tokens/*.json from this package
+// match the same schema.
+type tokenEntry struct {
+    ID       string `json:"id"`
+    Name     string `json:"name"`
+    Symbol   string `json:"symbol"`
+    Decimals int    `json:"decimals"`
+}
+
+raw, err := os.ReadFile("path/to/dist/tokens/sepolia.json")
+// ... json.Unmarshal(raw, &entries) ...
+```
+
+## Releasing
+
+This package uses [changesets](https://github.com/changesets/changesets) for versioning. The day-to-day flow:
+
+```bash
+# 1. Make your code changes on a feature branch.
+yarn changeset                   # interactive prompt; pick bump level + write the changelog entry
+git add .changeset && git commit -m "..."
+git push                         # open PR as normal
+```
+
+When the PR merges to `main`, the `Release` workflow (`.github/workflows/release.yml`) either:
+
+- Opens (or updates) a "Version Packages" PR that runs `yarn changeset version` — bumps `package.json` + writes `CHANGELOG.md`. Review and merge that PR.
+- Or, if there are no pending changesets, runs `yarn release` (`yarn build && yarn changeset publish`) — which publishes to npm with the right dist-tag automatically (stable → `latest`, pre-release → its identifier).
+
+### Publishing manually (escape hatch)
+
+If you need to publish without the GitHub Action — e.g. an emergency release from a machine that has `npm login` credentials:
+
+```bash
+yarn build                        # produces dist/ + tokens sidecar
+npm whoami                        # verify logged in
+npm publish --access public       # for stable versions; goes to `latest`
+# or for a pre-release:
+npm publish --access public --tag dev
+```
+
+`prepublishOnly: yarn build` runs the build chain automatically if you forget, so even `npm publish` alone is safe.
+
 ## Versioning
 
 Semver. Until `1.0.0`, breaking changes can land in minor versions (`0.x`), but address corrections are always patches.

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   Chains: () => Chains,
   Protocols: () => Protocols,
+  Tokens: () => Tokens,
   aaveV3: () => aaveV3,
   aerodrome: () => aerodrome,
   aggregatorV3Abi: () => aggregatorV3Abi,
@@ -32,6 +33,7 @@ __export(index_exports, {
   ethena: () => ethena,
   fraxEther: () => fraxEther,
   lido: () => lido,
+  lookupToken: () => lookupToken,
   morphoBlue: () => morphoBlue,
   rocketPool: () => rocketPool,
   sky: () => sky,
@@ -844,10 +846,176 @@ var Protocols = Object.freeze({
   uniswapV3,
   wrapped
 });
+
+// src/tokens/index.ts
+var USDC = {
+  [Chains.EthereumMainnet]: {
+    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    decimals: 6,
+    name: "USD Coin",
+    description: "Fully-reserved USD stablecoin issued by Circle.",
+    website: "https://www.circle.com/usdc",
+    explorer: "https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/USDC.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/usd-coin",
+      coinmarketcap: "https://coinmarketcap.com/currencies/usd-coin/"
+    }
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decimals: 6,
+    name: "USD Coin",
+    explorer: "https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  },
+  [Chains.Sepolia]: {
+    address: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    decimals: 6,
+    name: "USD Coin (Sepolia)",
+    explorer: "https://sepolia.etherscan.io/token/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
+  },
+  [Chains.BaseSepolia]: {
+    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    decimals: 6,
+    name: "USD Coin (Base Sepolia)",
+    explorer: "https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+  },
+  [Chains.BnbMainnet]: {
+    address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+    decimals: 18,
+    name: "Binance-Peg USD Coin",
+    explorer: "https://bscscan.com/token/0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
+  }
+};
+var USDT = {
+  [Chains.EthereumMainnet]: {
+    address: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    decimals: 6,
+    name: "Tether USD",
+    description: "USD-pegged stablecoin issued by Tether.",
+    website: "https://tether.to",
+    explorer: "https://etherscan.io/token/0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/USDT.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/tether",
+      coinmarketcap: "https://coinmarketcap.com/currencies/tether/"
+    }
+  },
+  [Chains.BnbMainnet]: {
+    address: "0x55d398326f99059fF775485246999027B3197955",
+    decimals: 18,
+    name: "Binance-Peg Tether USD",
+    explorer: "https://bscscan.com/token/0x55d398326f99059fF775485246999027B3197955"
+  }
+};
+var WETH = {
+  [Chains.EthereumMainnet]: {
+    address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    decimals: 18,
+    name: "Wrapped Ether",
+    description: "ERC-20 wrapper around native ETH, 1:1 backed.",
+    explorer: "https://etherscan.io/token/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/WETH.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/weth"
+    }
+  },
+  [Chains.Sepolia]: {
+    address: "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
+    decimals: 18,
+    name: "Wrapped Ether (Sepolia)",
+    explorer: "https://sepolia.etherscan.io/token/0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14"
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x4200000000000000000000000000000000000006",
+    decimals: 18,
+    name: "Wrapped Ether",
+    explorer: "https://basescan.org/token/0x4200000000000000000000000000000000000006"
+  },
+  [Chains.BaseSepolia]: {
+    address: "0x4200000000000000000000000000000000000006",
+    decimals: 18,
+    name: "Wrapped Ether (Base Sepolia)",
+    explorer: "https://sepolia.basescan.org/token/0x4200000000000000000000000000000000000006"
+  }
+};
+var DAI = {
+  [Chains.EthereumMainnet]: {
+    address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    decimals: 18,
+    name: "Dai Stablecoin",
+    description: "Decentralized USD-pegged stablecoin issued by MakerDAO.",
+    website: "https://makerdao.com",
+    explorer: "https://etherscan.io/token/0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/DAI.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/dai",
+      coinmarketcap: "https://coinmarketcap.com/currencies/multi-collateral-dai/"
+    }
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+    decimals: 18,
+    name: "Dai Stablecoin",
+    explorer: "https://basescan.org/token/0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb"
+  }
+};
+var LINK = {
+  [Chains.EthereumMainnet]: {
+    address: "0x514910771AF9Ca656af840dff83E8264EcF986CA",
+    decimals: 18,
+    name: "ChainLink Token",
+    description: "Native token of the Chainlink decentralized oracle network.",
+    website: "https://chain.link",
+    explorer: "https://etherscan.io/token/0x514910771AF9Ca656af840dff83E8264EcF986CA",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/LINK.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/chainlink",
+      coinmarketcap: "https://coinmarketcap.com/currencies/chainlink/"
+    }
+  },
+  [Chains.Sepolia]: {
+    // AAVE V3 faucet-mintable LINK on Sepolia — NOT canonical Chainlink LINK.
+    // Templates targeting the AAVE Sepolia market need this address; the real
+    // Chainlink LINK on Sepolia is at 0x779877A7B0D9E8603169DdbD7836e478b4624789.
+    address: "0xf8Fb3713D459D7C1018BD0A49D19b4C44290EBE5",
+    decimals: 18,
+    name: "ChainLink Token (AAVE Sepolia faucet)",
+    explorer: "https://sepolia.etherscan.io/token/0xf8Fb3713D459D7C1018BD0A49D19b4C44290EBE5"
+  }
+};
+var Tokens = Object.freeze({
+  USDC,
+  USDT,
+  WETH,
+  DAI,
+  LINK
+});
+function lookupToken(chainId, address) {
+  if (!address) return void 0;
+  const target = address.toLowerCase();
+  if (chainId) {
+    for (const [symbol, byChain] of Object.entries(Tokens)) {
+      const entry = byChain[chainId];
+      if (entry && entry.address.toLowerCase() === target) {
+        return { symbol, ...entry };
+      }
+    }
+  }
+  for (const [symbol, byChain] of Object.entries(Tokens)) {
+    for (const entry of Object.values(byChain)) {
+      if (entry && entry.address.toLowerCase() === target) {
+        return { symbol, ...entry };
+      }
+    }
+  }
+  return void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Chains,
   Protocols,
+  Tokens,
   aaveV3,
   aerodrome,
   aggregatorV3Abi,
@@ -858,6 +1026,7 @@ var Protocols = Object.freeze({
   ethena,
   fraxEther,
   lido,
+  lookupToken,
   morphoBlue,
   rocketPool,
   sky,

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./protocols";
 export { Chains, type ChainId } from "./chains";
+export { Tokens, lookupToken } from "./tokens";
+export type { TokenByChain, TokenChainEntry, TokenLinks } from "./tokens";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -800,9 +800,175 @@ var Protocols = Object.freeze({
   uniswapV3,
   wrapped
 });
+
+// src/tokens/index.ts
+var USDC = {
+  [Chains.EthereumMainnet]: {
+    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    decimals: 6,
+    name: "USD Coin",
+    description: "Fully-reserved USD stablecoin issued by Circle.",
+    website: "https://www.circle.com/usdc",
+    explorer: "https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/USDC.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/usd-coin",
+      coinmarketcap: "https://coinmarketcap.com/currencies/usd-coin/"
+    }
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decimals: 6,
+    name: "USD Coin",
+    explorer: "https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  },
+  [Chains.Sepolia]: {
+    address: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    decimals: 6,
+    name: "USD Coin (Sepolia)",
+    explorer: "https://sepolia.etherscan.io/token/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
+  },
+  [Chains.BaseSepolia]: {
+    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    decimals: 6,
+    name: "USD Coin (Base Sepolia)",
+    explorer: "https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+  },
+  [Chains.BnbMainnet]: {
+    address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+    decimals: 18,
+    name: "Binance-Peg USD Coin",
+    explorer: "https://bscscan.com/token/0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
+  }
+};
+var USDT = {
+  [Chains.EthereumMainnet]: {
+    address: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    decimals: 6,
+    name: "Tether USD",
+    description: "USD-pegged stablecoin issued by Tether.",
+    website: "https://tether.to",
+    explorer: "https://etherscan.io/token/0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/USDT.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/tether",
+      coinmarketcap: "https://coinmarketcap.com/currencies/tether/"
+    }
+  },
+  [Chains.BnbMainnet]: {
+    address: "0x55d398326f99059fF775485246999027B3197955",
+    decimals: 18,
+    name: "Binance-Peg Tether USD",
+    explorer: "https://bscscan.com/token/0x55d398326f99059fF775485246999027B3197955"
+  }
+};
+var WETH = {
+  [Chains.EthereumMainnet]: {
+    address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    decimals: 18,
+    name: "Wrapped Ether",
+    description: "ERC-20 wrapper around native ETH, 1:1 backed.",
+    explorer: "https://etherscan.io/token/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/WETH.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/weth"
+    }
+  },
+  [Chains.Sepolia]: {
+    address: "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
+    decimals: 18,
+    name: "Wrapped Ether (Sepolia)",
+    explorer: "https://sepolia.etherscan.io/token/0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14"
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x4200000000000000000000000000000000000006",
+    decimals: 18,
+    name: "Wrapped Ether",
+    explorer: "https://basescan.org/token/0x4200000000000000000000000000000000000006"
+  },
+  [Chains.BaseSepolia]: {
+    address: "0x4200000000000000000000000000000000000006",
+    decimals: 18,
+    name: "Wrapped Ether (Base Sepolia)",
+    explorer: "https://sepolia.basescan.org/token/0x4200000000000000000000000000000000000006"
+  }
+};
+var DAI = {
+  [Chains.EthereumMainnet]: {
+    address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    decimals: 18,
+    name: "Dai Stablecoin",
+    description: "Decentralized USD-pegged stablecoin issued by MakerDAO.",
+    website: "https://makerdao.com",
+    explorer: "https://etherscan.io/token/0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/DAI.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/dai",
+      coinmarketcap: "https://coinmarketcap.com/currencies/multi-collateral-dai/"
+    }
+  },
+  [Chains.BaseMainnet]: {
+    address: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+    decimals: 18,
+    name: "Dai Stablecoin",
+    explorer: "https://basescan.org/token/0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb"
+  }
+};
+var LINK = {
+  [Chains.EthereumMainnet]: {
+    address: "0x514910771AF9Ca656af840dff83E8264EcF986CA",
+    decimals: 18,
+    name: "ChainLink Token",
+    description: "Native token of the Chainlink decentralized oracle network.",
+    website: "https://chain.link",
+    explorer: "https://etherscan.io/token/0x514910771AF9Ca656af840dff83E8264EcF986CA",
+    logoUrl: "https://raw.githubusercontent.com/AvaProtocol/protocols/main/logos/ethereum/LINK.png",
+    links: {
+      coingecko: "https://www.coingecko.com/en/coins/chainlink",
+      coinmarketcap: "https://coinmarketcap.com/currencies/chainlink/"
+    }
+  },
+  [Chains.Sepolia]: {
+    // AAVE V3 faucet-mintable LINK on Sepolia — NOT canonical Chainlink LINK.
+    // Templates targeting the AAVE Sepolia market need this address; the real
+    // Chainlink LINK on Sepolia is at 0x779877A7B0D9E8603169DdbD7836e478b4624789.
+    address: "0xf8Fb3713D459D7C1018BD0A49D19b4C44290EBE5",
+    decimals: 18,
+    name: "ChainLink Token (AAVE Sepolia faucet)",
+    explorer: "https://sepolia.etherscan.io/token/0xf8Fb3713D459D7C1018BD0A49D19b4C44290EBE5"
+  }
+};
+var Tokens = Object.freeze({
+  USDC,
+  USDT,
+  WETH,
+  DAI,
+  LINK
+});
+function lookupToken(chainId, address) {
+  if (!address) return void 0;
+  const target = address.toLowerCase();
+  if (chainId) {
+    for (const [symbol, byChain] of Object.entries(Tokens)) {
+      const entry = byChain[chainId];
+      if (entry && entry.address.toLowerCase() === target) {
+        return { symbol, ...entry };
+      }
+    }
+  }
+  for (const [symbol, byChain] of Object.entries(Tokens)) {
+    for (const entry of Object.values(byChain)) {
+      if (entry && entry.address.toLowerCase() === target) {
+        return { symbol, ...entry };
+      }
+    }
+  }
+  return void 0;
+}
 export {
   Chains,
   Protocols,
+  Tokens,
   aaveV3,
   aerodrome,
   aggregatorV3Abi,
@@ -813,6 +979,7 @@ export {
   ethena,
   fraxEther,
   lido,
+  lookupToken,
   morphoBlue,
   rocketPool,
   sky,

package/dist/tokens/base-sepolia.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+    "name": "USD Coin (Base Sepolia)",
+    "symbol": "USDC",
+    "decimals": 6
+  },
+  {
+    "id": "0x4200000000000000000000000000000000000006",
+    "name": "Wrapped Ether (Base Sepolia)",
+    "symbol": "WETH",
+    "decimals": 18
+  }
+]

package/dist/tokens/base.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "0x50c5725949a6f0c72e6c4a641f24049a917db0cb",
+    "name": "Dai Stablecoin",
+    "symbol": "DAI",
+    "decimals": 18
+  },
+  {
+    "id": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    "name": "USD Coin",
+    "symbol": "USDC",
+    "decimals": 6
+  },
+  {
+    "id": "0x4200000000000000000000000000000000000006",
+    "name": "Wrapped Ether",
+    "symbol": "WETH",
+    "decimals": 18
+  }
+]

package/dist/tokens/bnb-mainnet.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
+    "name": "Binance-Peg USD Coin",
+    "symbol": "USDC",
+    "decimals": 18
+  },
+  {
+    "id": "0x55d398326f99059ff775485246999027b3197955",
+    "name": "Binance-Peg Tether USD",
+    "symbol": "USDT",
+    "decimals": 18
+  }
+]

package/dist/tokens/ethereum.json

@@ -0,0 +1,32 @@
+[
+  {
+    "id": "0x6b175474e89094c44da98b954eedeac495271d0f",
+    "name": "Dai Stablecoin",
+    "symbol": "DAI",
+    "decimals": 18
+  },
+  {
+    "id": "0x514910771af9ca656af840dff83e8264ecf986ca",
+    "name": "ChainLink Token",
+    "symbol": "LINK",
+    "decimals": 18
+  },
+  {
+    "id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+    "name": "USD Coin",
+    "symbol": "USDC",
+    "decimals": 6
+  },
+  {
+    "id": "0xdac17f958d2ee523a2206206994597c13d831ec7",
+    "name": "Tether USD",
+    "symbol": "USDT",
+    "decimals": 6
+  },
+  {
+    "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
+    "name": "Wrapped Ether",
+    "symbol": "WETH",
+    "decimals": 18
+  }
+]

package/dist/tokens/index.d.ts

@@ -0,0 +1,53 @@
+import { type TokenChainEntry } from "./types";
+export type { TokenByChain, TokenChainEntry, TokenLinks } from "./types";
+/**
+ * Symbol → per-chain entry. The outer object is frozen at module
+ * load, so the symbol set is immutable. The inner per-chain maps
+ * (e.g. `Tokens.USDC`) are NOT deep-frozen — callers must treat
+ * them as logically read-only. The shallow freeze is the right
+ * tradeoff: deep-freezing the chain maps + their entries on every
+ * import would add overhead for a guarantee no consumer has asked
+ * for. Add a deep-freeze pass here if a real misuse case emerges.
+ *
+ * Symbol keys are the canonical uppercase ERC-20 ticker (USDC, not
+ * usdc/Usdc). The catalog is intentionally not case-insensitive at
+ * this level — callers needing a fuzzy lookup should normalize at
+ * their own boundary.
+ */
+export declare const Tokens: Readonly<{
+    USDC: Partial<Record<number, TokenChainEntry>>;
+    USDT: Partial<Record<number, TokenChainEntry>>;
+    WETH: Partial<Record<number, TokenChainEntry>>;
+    DAI: Partial<Record<number, TokenChainEntry>>;
+    LINK: Partial<Record<number, TokenChainEntry>>;
+}>;
+/**
+ * Reverse lookup: given a contract address, find the token entry plus
+ * its symbol. Address matching is case-insensitive so callers can pass
+ * checksum or lowercase without normalizing upstream.
+ *
+ * Resolution strategy:
+ *   1. When `chainId` is provided, prefer a match registered for that
+ *      chain.
+ *   2. If no chain-specific match (or no chainId), scan every chain
+ *      for the address. Necessary when the caller's chain context
+ *      diverges from where the address actually lives — happens in
+ *      multi-chain dev gateways where the workflow targets one chain
+ *      but the runtime is bound to a different one. Most ERC-20
+ *      addresses are globally unique so this collapses to a single
+ *      match; for OP-stack predeploys (e.g. WETH at 0x4200…0006 on
+ *      both Base and Base Sepolia), any match yields the correct
+ *      symbol and decimals.
+ *
+ * Returns `undefined` when no chain in the catalog carries the
+ * address, or when the address is missing/falsy.
+ *
+ * Typical use: aggregator payloads ship `tokenSymbol="UNKNOWN"` for
+ * tokens whose chain-specific RPC enrichment failed; consumers fall
+ * through to `lookupToken(chainId, contractAddress)` and recover the
+ * symbol + decimals from this catalog.
+ */
+export declare function lookupToken(chainId: number | undefined, address: string | undefined): (TokenChainEntry & {
+    symbol: string;
+}) | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AA+IzE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;;;;;;EAMgC,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,CAAC,eAAe,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAsBpD"}

package/dist/tokens/sepolia.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "0xf8fb3713d459d7c1018bd0a49d19b4c44290ebe5",
+    "name": "ChainLink Token (AAVE Sepolia faucet)",
+    "symbol": "LINK",
+    "decimals": 18
+  },
+  {
+    "id": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
+    "name": "USD Coin (Sepolia)",
+    "symbol": "USDC",
+    "decimals": 6
+  },
+  {
+    "id": "0xfff9976782d46cc05630d1f6ebab18b2324d6b14",
+    "name": "Wrapped Ether (Sepolia)",
+    "symbol": "WETH",
+    "decimals": 18
+  }
+]

package/dist/tokens/types.d.ts

@@ -0,0 +1,47 @@
+import { type ChainId } from "../chains";
+/**
+ * External reference links for a token. All fields optional — the
+ * catalog only records what's actually known per token. Add new keys
+ * here when adding a category we want to surface; consumers ignore
+ * unknown keys harmlessly.
+ */
+export interface TokenLinks {
+    readonly github?: string;
+    readonly twitter?: string;
+    readonly coingecko?: string;
+    readonly coinmarketcap?: string;
+    readonly reddit?: string;
+    readonly blog?: string;
+    readonly whitepaper?: string;
+}
+/**
+ * Per-chain token deployment record. `address` and `decimals` are
+ * required because they're the universal lookup primitives every
+ * consumer needs. All other fields are optional metadata.
+ *
+ * `name` is per-chain because some tokens use different display names
+ * on different deployments (e.g. AAVE's faucet-LINK on Sepolia is
+ * "ChainLink Token" vs. "Chainlink" on mainnet). When the chains
+ * agree, the same string is fine to repeat.
+ *
+ * `logoUrl` is a fully qualified URL — typically a GitHub Raw or CDN
+ * link. Studio renders local PNGs by resolving symbol+chain itself
+ * and ignores this field; backend consumers may surface the URL
+ * directly in summaries or skip it.
+ */
+export interface TokenChainEntry {
+    readonly address: `0x${string}`;
+    readonly decimals: number;
+    readonly name?: string;
+    readonly description?: string;
+    readonly website?: string;
+    readonly explorer?: string;
+    readonly logoUrl?: string;
+    readonly links?: TokenLinks;
+}
+/**
+ * Map of `ChainId → TokenChainEntry`. `Partial` because no token is
+ * deployed on every chain in the catalog.
+ */
+export type TokenByChain = Partial<Record<ChainId, TokenChainEntry>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/tokens/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tokens/types.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avaprotocol/protocols",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Multi-chain catalog of DeFi protocol contract addresses, ABI fragments, and event topic hashes — covers AAVE V3, Uniswap V3, Chainlink, Lido, Morpho, and more.",
   "keywords": [
     "defi",
@@ -50,17 +50,23 @@
   "scripts": {
     "build:declarations": "tsc -p tsconfig.build.json",
     "build:js": "tsup src/index.ts --format cjs,esm --target es2020",
-    "build": "yarn clean:dist && yarn build:declarations && yarn build:js",
+    "build:tokens-sidecar": "tsx scripts/build-tokens-sidecar.ts",
+    "build": "yarn clean:dist && yarn build:declarations && yarn build:js && yarn build:tokens-sidecar",
     "clean": "rm -rf node_modules dist tsconfig.tsbuildinfo",
     "clean:dist": "rm -rf dist tsconfig.tsbuildinfo",
     "test": "vitest",
     "test:run": "vitest run",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "yarn build",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "yarn build && changeset publish"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.5.4",
     "vitest": "^1.6.0"
   },