Class: AssetRegistry
Defined in: packages/overcast-core/src/assets/registry.ts:40
An in-memory lookup from (domain, asset address) to its curated Asset metadata.
Keyed by the pair, not the address alone: an address is only unique within
a domain. A store fed by a multi-domain indexer holds rows from every chain
its indexer scans, and two EVM domains can perfectly well use the same address
for different tokens — resolving those through one flat address map is how an
asset silently gets the wrong symbol and, worse, the wrong decimals. The
domain is on every row (OptionDetails.domain), so the pair is always
knowable at lookup time. This is the asset-side counterpart of
OvercastUtilsRegistry, which keys the address boundary the same way.
An asset registered without a domain is a wildcard: it answers for any
domain that has no asset of its own at that address. That keeps a
single-domain backend — which has nothing to disambiguate, and today stamps no
domain on its metadata — working unchanged, while a deployment that serves two
domains gets exact resolution as soon as it starts stamping them.
A miss is not a rejection. The registry describes assets, it does not gate them: the protocol trades whatever an offer's terms name, so an unregistered asset still deposits, still prices, still settles — it just renders as a bare address in native units. Which is why the resolution a display path wants is getOrDefault, not require.
The core package ships the class only — it is deliberately never populated here. Each deployment (e.g. the backend) constructs an instance from the metadata it maintains.
Constructors
Constructor
new AssetRegistry(assets?): AssetRegistry;
Defined in: packages/overcast-core/src/assets/registry.ts:55
Parameters
| Parameter | Type | Default value |
|---|---|---|
assets | object[] | [] |
Returns
AssetRegistry
Methods
bySymbol()
bySymbol(symbol, domain?):
| {
address: string;
cashLike?: boolean;
chain?: string;
coinGeckoId?: string;
decimals?: number;
domain?: number;
lastKnownPriceUsd?: number;
logoUrl?: string;
name?: string;
rwa?: boolean;
symbol?: string;
volatility?: number;
}
| undefined;
Defined in: packages/overcast-core/src/assets/registry.ts:146
The asset with symbol on domain, for resolving a human-typed ticker
(a CLI flag, a search box). Case-insensitive; the first match wins, so a
deployment with two assets sharing a ticker on one domain should be
addressed by address instead.
Parameters
| Parameter | Type |
|---|---|
symbol | string |
domain? | number |
Returns
Type Literal
{
address: string;
cashLike?: boolean;
chain?: string;
coinGeckoId?: string;
decimals?: number;
domain?: number;
lastKnownPriceUsd?: number;
logoUrl?: string;
name?: string;
rwa?: boolean;
symbol?: string;
volatility?: number;
}
address
address: string;
The on-chain address (mint) identifying the asset, in the layer's own
encoding (base58 on Solana, 0x… on an EVM chain) — see Address.
cashLike?
optional cashLike?: boolean;
Whether or not the asset can be treated similar to cash
chain?
optional chain?: string;
The chain the asset lives on, e.g. "base". A display label only — it
is a caller-chosen name (see ChainName), carried by no wire payload
and never used to key or look up an asset. domain is the identity.
coinGeckoId?
optional coinGeckoId?: string;
CoinGecko id for price lookups, e.g. usd-coin.
decimals?
optional decimals?: number;
Number of decimal places in the asset's native units.
domain?
optional domain?: number;
The protocol domain the asset lives on — the same separator
OptionDetails.domain carries and every indexed event is tagged with, and
the first half of the asset's key in an AssetRegistry.
Optional because a single-domain deployment has nothing to disambiguate; such an asset registers as a wildcard, matching any domain that has no asset of its own at that address. Populate it as soon as one backend serves two domains — an address is only unique within a domain.
lastKnownPriceUsd?
optional lastKnownPriceUsd?: number;
Last known USD price, sourced best-effort from an external feed (CoinGecko). Untrusted — do not use for settlement, signing, valuation, or any value transfer. It is informational only (e.g. showing an approximate notional in a picker), may be stale, missing, or wrong, and is never part of the canonical, content-addressed asset identity. Present only once a price has actually been fetched for the asset.
logoUrl?
optional logoUrl?: string;
Logo of the coin
name?
optional name?: string;
Human name of the asset.
rwa?
optional rwa?: boolean;
Whether the asset is a real-world asset (RWA) — e.g. tokenized private equity — rather than a native crypto asset.
symbol?
optional symbol?: string;
Human ticker, e.g. USDC.
volatility?
optional volatility?: number;
Volatility of the asset
undefined
domains()
domains(): number[];
Defined in: packages/overcast-core/src/assets/registry.ts:152
The domains that have at least one asset of their own, in insertion order.
Returns
number[]
get()
get(address, domain?):
| {
address: string;
cashLike?: boolean;
chain?: string;
coinGeckoId?: string;
decimals?: number;
domain?: number;
lastKnownPriceUsd?: number;
logoUrl?: string;
name?: string;
rwa?: boolean;
symbol?: string;
volatility?: number;
}
| undefined;
Defined in: packages/overcast-core/src/assets/registry.ts:92
The asset at address on domain, or undefined if none is registered.
Falls back to a wildcard asset at that address (see the class docs) before
giving up.
Omitting domain answers from the domain-less index instead, which is
inherently ambiguous once an address exists on several domains — pass the
domain wherever the caller has one, which for anything read out of a store
is always.
Parameters
| Parameter | Type |
|---|---|
address | Address |
domain? | number |
Returns
Type Literal
{
address: string;
cashLike?: boolean;
chain?: string;
coinGeckoId?: string;
decimals?: number;
domain?: number;
lastKnownPriceUsd?: number;
logoUrl?: string;
name?: string;
rwa?: boolean;
symbol?: string;
volatility?: number;
}
address
address: string;
The on-chain address (mint) identifying the asset, in the layer's own
encoding (base58 on Solana, 0x… on an EVM chain) — see Address.
cashLike?
optional cashLike?: boolean;
Whether or not the asset can be treated similar to cash
chain?
optional chain?: string;
The chain the asset lives on, e.g. "base". A display label only — it
is a caller-chosen name (see ChainName), carried by no wire payload
and never used to key or look up an asset. domain is the identity.
coinGeckoId?
optional coinGeckoId?: string;
CoinGecko id for price lookups, e.g. usd-coin.
decimals?
optional decimals?: number;
Number of decimal places in the asset's native units.
domain?
optional domain?: number;
The protocol domain the asset lives on — the same separator
OptionDetails.domain carries and every indexed event is tagged with, and
the first half of the asset's key in an AssetRegistry.
Optional because a single-domain deployment has nothing to disambiguate; such an asset registers as a wildcard, matching any domain that has no asset of its own at that address. Populate it as soon as one backend serves two domains — an address is only unique within a domain.
lastKnownPriceUsd?
optional lastKnownPriceUsd?: number;
Last known USD price, sourced best-effort from an external feed (CoinGecko). Untrusted — do not use for settlement, signing, valuation, or any value transfer. It is informational only (e.g. showing an approximate notional in a picker), may be stale, missing, or wrong, and is never part of the canonical, content-addressed asset identity. Present only once a price has actually been fetched for the asset.
logoUrl?
optional logoUrl?: string;
Logo of the coin
name?
optional name?: string;
Human name of the asset.
rwa?
optional rwa?: boolean;
Whether the asset is a real-world asset (RWA) — e.g. tokenized private equity — rather than a native crypto asset.
symbol?
optional symbol?: string;
Human ticker, e.g. USDC.
volatility?
optional volatility?: number;
Volatility of the asset
undefined
getOrDefault()
getOrDefault(address, domain?): object;
Defined in: packages/overcast-core/src/assets/registry.ts:131
Like get, but falls back to a bare Asset carrying just the
address (and the domain it was looked up on) when nothing is registered — so
a curation path can always answer, with an unresolved asset rather than a
throw. Such an asset has no decimals, which means amounts against it are
shown in native units; that is the honest rendering of "we don't know this
token".
Parameters
| Parameter | Type |
|---|---|
address | Address |
domain? | number |
Returns
address
address: string;
The on-chain address (mint) identifying the asset, in the layer's own
encoding (base58 on Solana, 0x… on an EVM chain) — see Address.
cashLike?
optional cashLike?: boolean;
Whether or not the asset can be treated similar to cash
chain?
optional chain?: string;
The chain the asset lives on, e.g. "base". A display label only — it
is a caller-chosen name (see ChainName), carried by no wire payload
and never used to key or look up an asset. domain is the identity.
coinGeckoId?
optional coinGeckoId?: string;
CoinGecko id for price lookups, e.g. usd-coin.
decimals?
optional decimals?: number;
Number of decimal places in the asset's native units.
domain?
optional domain?: number;
The protocol domain the asset lives on — the same separator
OptionDetails.domain carries and every indexed event is tagged with, and
the first half of the asset's key in an AssetRegistry.
Optional because a single-domain deployment has nothing to disambiguate; such an asset registers as a wildcard, matching any domain that has no asset of its own at that address. Populate it as soon as one backend serves two domains — an address is only unique within a domain.
lastKnownPriceUsd?
optional lastKnownPriceUsd?: number;
Last known USD price, sourced best-effort from an external feed (CoinGecko). Untrusted — do not use for settlement, signing, valuation, or any value transfer. It is informational only (e.g. showing an approximate notional in a picker), may be stale, missing, or wrong, and is never part of the canonical, content-addressed asset identity. Present only once a price has actually been fetched for the asset.
logoUrl?
optional logoUrl?: string;
Logo of the coin
name?
optional name?: string;
Human name of the asset.
rwa?
optional rwa?: boolean;
Whether the asset is a real-world asset (RWA) — e.g. tokenized private equity — rather than a native crypto asset.
symbol?
optional symbol?: string;
Human ticker, e.g. USDC.
volatility?
optional volatility?: number;
Volatility of the asset
has()
has(address, domain?): boolean;
Defined in: packages/overcast-core/src/assets/registry.ts:101
Whether address has curated metadata on domain.
Parameters
| Parameter | Type |
|---|---|
address | Address |
domain? | number |
Returns
boolean
list()
list(domain?): object[];
Defined in: packages/overcast-core/src/assets/registry.ts:76
Every asset registered for domain — its own plus the wildcards that answer
for it — in insertion order. Omit domain for the whole registry.
Parameters
| Parameter | Type |
|---|---|
domain? | number |
Returns
register()
register(asset): this;
Defined in: packages/overcast-core/src/assets/registry.ts:60
Add (or overwrite) an asset, keyed by its (domain, address) pair.
Parameters
| Parameter | Type | Description |
|---|---|---|
asset | { address: string; cashLike?: boolean; chain?: string; coinGeckoId?: string; decimals?: number; domain?: number; lastKnownPriceUsd?: number; logoUrl?: string; name?: string; rwa?: boolean; symbol?: string; volatility?: number; } | - |
asset.address | string | The on-chain address (mint) identifying the asset, in the layer's own encoding (base58 on Solana, 0x… on an EVM chain) — see Address. |
asset.cashLike? | boolean | Whether or not the asset can be treated similar to cash |
asset.chain? | string | The chain the asset lives on, e.g. "base". A display label only — it is a caller-chosen name (see ChainName), carried by no wire payload and never used to key or look up an asset. domain is the identity. |
asset.coinGeckoId? | string | CoinGecko id for price lookups, e.g. usd-coin. |
asset.decimals? | number | Number of decimal places in the asset's native units. |
asset.domain? | number | The protocol domain the asset lives on — the same separator OptionDetails.domain carries and every indexed event is tagged with, and the first half of the asset's key in an AssetRegistry. Optional because a single-domain deployment has nothing to disambiguate; such an asset registers as a wildcard, matching any domain that has no asset of its own at that address. Populate it as soon as one backend serves two domains — an address is only unique within a domain. |
asset.lastKnownPriceUsd? | number | Last known USD price, sourced best-effort from an external feed (CoinGecko). Untrusted — do not use for settlement, signing, valuation, or any value transfer. It is informational only (e.g. showing an approximate notional in a picker), may be stale, missing, or wrong, and is never part of the canonical, content-addressed asset identity. Present only once a price has actually been fetched for the asset. |
asset.logoUrl? | string | Logo of the coin |
asset.name? | string | Human name of the asset. |
asset.rwa? | boolean | Whether the asset is a real-world asset (RWA) — e.g. tokenized private equity — rather than a native crypto asset. |
asset.symbol? | string | Human ticker, e.g. USDC. |
asset.volatility? | number | Volatility of the asset |
Returns
this
require()
require(address, domain?): object;
Defined in: packages/overcast-core/src/assets/registry.ts:111
Like get, but throws when the asset isn't registered. For a caller
that genuinely cannot proceed without the metadata (scaling a human-typed
amount by decimals, say) — never as a support check, since an unregistered
asset is still tradeable.
Parameters
| Parameter | Type |
|---|---|
address | Address |
domain? | number |
Returns
address
address: string;
The on-chain address (mint) identifying the asset, in the layer's own
encoding (base58 on Solana, 0x… on an EVM chain) — see Address.
cashLike?
optional cashLike?: boolean;
Whether or not the asset can be treated similar to cash
chain?
optional chain?: string;
The chain the asset lives on, e.g. "base". A display label only — it
is a caller-chosen name (see ChainName), carried by no wire payload
and never used to key or look up an asset. domain is the identity.
coinGeckoId?
optional coinGeckoId?: string;
CoinGecko id for price lookups, e.g. usd-coin.
decimals?
optional decimals?: number;
Number of decimal places in the asset's native units.
domain?
optional domain?: number;
The protocol domain the asset lives on — the same separator
OptionDetails.domain carries and every indexed event is tagged with, and
the first half of the asset's key in an AssetRegistry.
Optional because a single-domain deployment has nothing to disambiguate; such an asset registers as a wildcard, matching any domain that has no asset of its own at that address. Populate it as soon as one backend serves two domains — an address is only unique within a domain.
lastKnownPriceUsd?
optional lastKnownPriceUsd?: number;
Last known USD price, sourced best-effort from an external feed (CoinGecko). Untrusted — do not use for settlement, signing, valuation, or any value transfer. It is informational only (e.g. showing an approximate notional in a picker), may be stale, missing, or wrong, and is never part of the canonical, content-addressed asset identity. Present only once a price has actually been fetched for the asset.
logoUrl?
optional logoUrl?: string;
Logo of the coin
name?
optional name?: string;
Human name of the asset.
rwa?
optional rwa?: boolean;
Whether the asset is a real-world asset (RWA) — e.g. tokenized private equity — rather than a native crypto asset.
symbol?
optional symbol?: string;
Human ticker, e.g. USDC.
volatility?
optional volatility?: number;
Volatility of the asset