@chipi-stack/core is in development (v0.1.0). APIs may change before stable release.
Overview
TokenRegistry provides a lookup table for token metadata (symbol, decimals, address, name) on StarkNet networks. It ships with built-in presets for mainnet and Sepolia, eliminating the need to hardcode token addresses.
Usage
import { TokenRegistry, Amount } from "@chipi-stack/core";
const registry = new TokenRegistry("mainnet");
const usdc = registry.bySymbol("USDC")!;
console.log(usdc.address); // "0x033068F6539..."
console.log(usdc.decimals); // 6
// Use with Amount
const amount = Amount.parse("10.0", usdc);
Constructor
new TokenRegistry(network: "mainnet" | "sepolia")
Parameters
network ("mainnet" | "sepolia"): The StarkNet network to load presets for
Throws
- If
network is not "mainnet" or "sepolia"
Methods
bySymbol(symbol)
Find a token by its symbol (case-insensitive).
const eth = registry.bySymbol("ETH");
const usdc = registry.bySymbol("usdc"); // case-insensitive
Parameters
symbol (string): Token symbol (e.g., "USDC", "ETH")
Returns
TokenEntry | undefined
byAddress(address)
Find a token by its contract address (case-insensitive).
// Native USDC on Starknet mainnet (not USDC.e bridged)
const token = registry.byAddress("0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb");
console.log(token?.symbol); // "USDC"
Parameters
address (string): Token contract address
Returns
TokenEntry | undefined
all()
List all tokens in this registry.
const tokens = registry.all();
console.log(tokens.map(t => t.symbol)); // ["ETH", "USDC", "USDT", "DAI", "STRK", "WBTC"]
Returns
TokenEntry[]
Built-in Presets
Mainnet
| Symbol | Decimals | Name |
|---|
| ETH | 18 | Ether |
| USDC | 6 | USD Coin |
| USDT | 6 | Tether USD |
| DAI | 18 | Dai Stablecoin |
| STRK | 18 | Starknet Token |
| WBTC | 8 | Wrapped Bitcoin |
Sepolia (Testnet)
| Symbol | Decimals | Name |
|---|
| ETH | 18 | Ether |
| USDC | 6 | USD Coin (Testnet) |
| STRK | 18 | Starknet Token |
TokenEntry Type
interface TokenEntry {
symbol: string; // e.g., "USDC"
decimals: number; // e.g., 6
address: string; // StarkNet contract address
name: string; // e.g., "USD Coin"
}
TokenEntry extends TokenInfo (used by Amount.parse()) with an additional name field.
Example
import { TokenRegistry, Amount, Erc20 } from "@chipi-stack/core";
// Set up registry for the target network
const network = process.env.STARKNET_NETWORK === "mainnet" ? "mainnet" : "sepolia";
const registry = new TokenRegistry(network);
// Look up token and create typed wrapper
const usdcInfo = registry.bySymbol("USDC");
if (!usdcInfo) throw new Error("USDC not found in registry");
const usdc = new Erc20(usdcInfo, account);
const amount = Amount.parse("50.0", usdcInfo);
const balance = await usdc.balanceOf(myAddress);
console.log(`Balance: ${balance.toFormatted()}`);
- Amount: Use TokenEntry from the registry with
Amount.parse()
- Erc20: Pass TokenEntry to the Erc20 constructor
