Agent guidance for resolving contract and token names

​

Objectives

• Normalize a user query (e.g., “WETH”, “weth”, “wstETH”) to a set of canonical candidates
• Locate the primary interfaces under mintlify_context/
• Surface related wrappers and bridged/vault tokens (e.g., vb*, bvb* variants)
• Offer adjacent resources (e.g., price oracles) for the same asset symbol
• Warn about likely pitfalls (case, prefixes, ambiguous aliases)

​

Directory map and naming patterns

• Base/asset tokens: mintlify_context/tokens/
  • Filenames follow the pattern I<Symbol>.md or vendor-form names like IweETH.md, IwstETH.md, IAUSD.md, ISUSHI.md, IYFI.md, IPOL.md, IKAT.md, etc.
• Vault/bridge tokens: mintlify_context/vb/tokens/
  • Primary pattern: Ivb<Symbol>.md (e.g., IvbETH.md, IvbUSDC.md, IvbUSDT.md, IvbWBTC.md, IvbUSDS.md).
  • Also present: Ibvb<Symbol>.md (e.g., IbvbEth.md, IbvbUSDC.md, IbvbUSDT.md, IbvbWBTC.md, IbvbUSDS.md). Treat vb and bvb variants as equivalent wrappers over the base symbol.
• Price oracles: mintlify_context/oracles/chainlink/ and mintlify_context/oracles/redstone/
  • Common patterns:
    • I<Symbol>USDOracle.md (e.g., IUSDCUSDOracle.md, IWBTCUSDOracle.md, IYFIUSDOracle.md)
    • Cross-asset oracles such as ILBTCBTCOracle.md, IwstETHETHOracle.md, IweETHETHOracle.md

​

Normalization and candidate generation

1. Trim and case-normalize: Convert to upper/lower variants without losing meaningful vendor prefixes. Examples: WETH, weETH, wstETH, USDC, WBTC.
2. Split vendor prefixes: Recognize known wrappers/prefixes and the base symbol:
   • w* (wrapped), we* (e.g., weETH), wst* (e.g., wstETH)
   • vb* and bvb* (vault/bridge wrappers) → base symbol remains after the prefix
   • Other observed prefixes: u* (e.g., uBTC, uSOL, uSUI), ecosystem/vendor names (e.g., JitoSOL)
3. Generate filename candidates in this order:
   • Token interfaces: I<Symbol>.md, I<vendorSymbol>.md (e.g., IweETH.md, IwstETH.md)
   • Vault/bridge: Ivb<Symbol>.md, Ibvb<Symbol>.md (case-tolerant for ETH vs Eth)
   • Oracles: I<Symbol>USDOracle.md, I<Symbol><Quote>Oracle.md as applicable
4. De-duplicate candidates and proceed with the search order below.

​

Deterministic search order

​

Synonym and alias guidance

• WETH-related:
  • Base concept: ETH wrapped variants may appear as WETH (generic), weETH, or wstETH. These are distinct assets but often requested together.
  • Vault/bridge wrappers: look for IvbETH.md and IbvbEth.md under vb/tokens/ when the query is about WETH/ETH.
  • Present both base/vendor tokens (e.g., IweETH.md, IwstETH.md) and wrapper tokens (IvbETH.md, IbvbEth.md) as related, clearly labeled.
• WBTC-related:
  • Base token and wrappers: IvbWBTC.md, IbvbWBTC.md; price oracles: IWBTCUSDOracle.md, IWBTCBTCOracle.md.
• Stablecoins (USDC, USDT, USDS, AUSD):
  • USDC: IvbUSDC.md, IbvbUSDC.md, IUSDCUSDOracle.md
  • USDT: IvbUSDT.md, IbvbUSDT.md, IUSDTUSDOracle.md
  • USDS: IvbUSDS.md, IbvbUSDS.md, IUSDSUSDOracle.md
  • AUSD: IAUSD.md, IAUSDUSDOracle.md
• Other examples:
  • YFI: IYFI.md, IYFIUSDOracle.md
  • POL (Polygon): IPOL.md, IPOLUSDOracle.md
  • LSTs: IwstETH.md, IweETH.md, with corresponding ...ETHOracle.md
  • u-prefixed tokens: IuBTC.md, IuSOL.md, IuSUI.md → treat u* as part of the symbol, not the vb/bvb family.

​

Pitfalls to avoid

• Case variance: Some files use ETH vs Eth (e.g., IbvbEth.md). Perform case-insensitive matching and present the exact file path.
• Prefix collisions: w*/we*/wst* vs vb*/bvb* serve different purposes. Do not conflate them.
• Ambiguous aliases: LBTC vs WBTC vs BTCK are not interchangeable. Use oracles and directory context to disambiguate.
• Symbol vs protocol: Queries like “Morpho” or “Sushi” are protocols; search those subdirectories first before token directories.
• Interface prefix: All interface docs begin with I. Remember to prepend I when forming filename candidates.

​

Example: resolving a WETH query

​

Example: resolving a WBTC query

• tokens/: (base interfaces may not exist for IWBTC.md here)
• vb/tokens/: IvbWBTC.md, IbvbWBTC.md
• oracles/: IWBTCUSDOracle.md, IWBTCBTCOracle.md

​

Output requirements for agents

• Always include exact file paths and interface names you found.
• Group results into: primary match(es), wrappers (vb/bvb), vendor tokens, oracles, and adjacent protocol docs.
• Call out ambiguities explicitly in prose when similar assets exist.
• Do not overstate equivalence: where assets are related but distinct, label them as such.