@avaprotocol/protocols 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @avaprotocol/protocols
 
+## 0.4.1
+
+### Patch Changes
+
+- 9460f61: `lookupToken` now walks per-protocol `tokens` tables (`Protocols.aaveV3.tokens.LINK`, `Protocols.uniswapV3.tokens.WETH`, etc.) as a third resolution pass after the top-level `Tokens` catalog scan. Covers token addresses that ship alongside a specific protocol but don't appear in the top-level catalog — most notably the AAVE-V3 Sepolia faucet LINK (`0xf8Fb37…0EBE5`), which is the address AAVE templates actually use on Sepolia even though the canonical Chainlink LINK (`0x779877…4789`) lives elsewhere.
+
+  When the symbol resolved from a per-protocol map also appears in `Tokens` on some chain, decimals/name are lifted from there; otherwise decimals default to 18 (true for every per-protocol token currently shipped).
+
+  Fixes a regression introduced by 0.4.0's Studio seed where `Tokens.LINK[Sepolia]` switched to the canonical Chainlink address, leaving consumers unable to recover the symbol for the AAVE template's faucet address.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1636,6 +1636,7 @@ function buildTokensFromData() {
   return merged;
 }
 var Tokens = Object.freeze(buildTokensFromData());
+var PROTOCOL_TOKEN_DEFAULT_DECIMALS = 18;
 function lookupToken(chainId, address) {
   if (!address) return void 0;
   const target = address.toLowerCase();
@@ -1654,6 +1655,26 @@ function lookupToken(chainId, address) {
       }
     }
   }
+  for (const protocolModule of Object.values(Protocols)) {
+    const tokens3 = protocolModule.tokens;
+    if (!tokens3 || typeof tokens3 !== "object") continue;
+    for (const [symbol, addressMap] of Object.entries(tokens3)) {
+      if (!addressMap || typeof addressMap !== "object") continue;
+      for (const [rawChainId, addr] of Object.entries(addressMap)) {
+        if (typeof addr !== "string") continue;
+        if (addr.toLowerCase() !== target) continue;
+        const resolvedChainId = Number(rawChainId);
+        const canonicalSymbolByChain = Tokens[symbol];
+        const metadataSource = canonicalSymbolByChain?.[resolvedChainId] ?? (canonicalSymbolByChain ? Object.values(canonicalSymbolByChain).find((e) => e) : void 0);
+        return {
+          symbol,
+          address: addr,
+          decimals: metadataSource?.decimals ?? PROTOCOL_TOKEN_DEFAULT_DECIMALS,
+          ...metadataSource?.name ? { name: metadataSource.name } : {}
+        };
+      }
+    }
+  }
   return void 0;
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js

@@ -1590,6 +1590,7 @@ function buildTokensFromData() {
   return merged;
 }
 var Tokens = Object.freeze(buildTokensFromData());
+var PROTOCOL_TOKEN_DEFAULT_DECIMALS = 18;
 function lookupToken(chainId, address) {
   if (!address) return void 0;
   const target = address.toLowerCase();
@@ -1608,6 +1609,26 @@ function lookupToken(chainId, address) {
       }
     }
   }
+  for (const protocolModule of Object.values(Protocols)) {
+    const tokens3 = protocolModule.tokens;
+    if (!tokens3 || typeof tokens3 !== "object") continue;
+    for (const [symbol, addressMap] of Object.entries(tokens3)) {
+      if (!addressMap || typeof addressMap !== "object") continue;
+      for (const [rawChainId, addr] of Object.entries(addressMap)) {
+        if (typeof addr !== "string") continue;
+        if (addr.toLowerCase() !== target) continue;
+        const resolvedChainId = Number(rawChainId);
+        const canonicalSymbolByChain = Tokens[symbol];
+        const metadataSource = canonicalSymbolByChain?.[resolvedChainId] ?? (canonicalSymbolByChain ? Object.values(canonicalSymbolByChain).find((e) => e) : void 0);
+        return {
+          symbol,
+          address: addr,
+          decimals: metadataSource?.decimals ?? PROTOCOL_TOKEN_DEFAULT_DECIMALS,
+          ...metadataSource?.name ? { name: metadataSource.name } : {}
+        };
+      }
+    }
+  }
   return void 0;
 }
 export {

package/dist/tokens/index.d.ts

@@ -28,18 +28,34 @@ export declare const Tokens: Readonly<Record<string, TokenByChain>>;
  *
  * Resolution strategy:
  *   1. When `chainId` is provided, prefer a match registered for that
- *      chain.
+ *      chain in the top-level `Tokens` catalog.
  *   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. The fallback is
- *      best-effort: the same 20-byte address is reachable on every
- *      EVM chain, so the scan only happens to be correct because the
- *      catalog only ships well-known canonical tokens whose contract
- *      addresses (mainnet USDC, OP-stack WETH predeploys, etc.) don't
- *      collide across chains in practice. Callers should still pass
- *      the right chainId when they have it.
+ *      in `Tokens` 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. The
+ *      fallback is best-effort: the same 20-byte address is
+ *      reachable on every EVM chain, so the scan only happens to be
+ *      correct because the catalog only ships well-known canonical
+ *      tokens whose contract addresses (mainnet USDC, OP-stack WETH
+ *      predeploys, etc.) don't collide across chains in practice.
+ *      Callers should still pass the right chainId when they have it.
+ *   3. If still no match, walk every per-protocol `tokens` table
+ *      (`Protocols.aaveV3.tokens.LINK`, `Protocols.uniswapV3.tokens.WETH`,
+ *      ...) for the address. Catches token addresses that ship
+ *      alongside a specific protocol — most notably the AAVE-V3
+ *      Sepolia faucet LINK (`0xf8Fb37…0EBE5`), which is the address
+ *      AAVE templates actually use on Sepolia even though the
+ *      canonical Chainlink LINK lives elsewhere. When the symbol
+ *      resolved from a per-protocol map also appears in `Tokens`,
+ *      `decimals` and `name` are lifted from the same-chain catalog
+ *      entry when one exists, else from any other catalog entry
+ *      under that symbol; `decimals` defaults to 18 when no catalog
+ *      entry exists at all (true for every per-protocol token the
+ *      catalog currently ships). The catalog's URL-shaped fields
+ *      (`website`, `explorer`, `logoUrl`, `links`) are intentionally
+ *      NOT lifted — they're per-deployment metadata that a faucet
+ *      variant would render incorrectly.
  *
  * Returns `undefined` when no chain in the catalog carries the
  * address, or when the address is missing/falsy.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAQlE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAqDzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAwC,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAQlE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAqDzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAwC,CAAC;AAcnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;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,CA6DpD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avaprotocol/protocols",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",