tribulnation-catalogue

Python client for the Tribulnation Catalogue — a typed, open catalogue of crypto assets, trading platforms, and instrument mappings.

Install

pip install tribulnation-catalogue

Usage

from tribulnation.catalogue import Catalogue

catalogue = Catalogue.load()

btc     = catalogue.assets["bitcoin"]
binance = catalogue.platforms["binance"]

load() keeps the published data.zip in ~/.cache/tribulnation and loads it from there. Once a day (max_age) it asks the site whether the archive changed with one conditional request (ETag / Last-Modified), and downloads it again only when it did. A download replaces the cached copy only once it loads; if the site is unreachable, the last good copy is used and a warning is logged. Only a first run without any cached copy fails.

Loading options

# Cached archive, checked at most once a day (default)
catalogue = Catalogue.load()

# Check more or less often
catalogue = Catalogue.load(max_age=timedelta(hours=6))

# Force a fresh download
catalogue = Catalogue.load(refresh=True)

# Load from an explicit local folder (never touches the network once it exists)
catalogue = Catalogue.load("data")

# Custom source URL or cache directory
catalogue = Catalogue.load(
    url="https://my-mirror.example.com/data.zip",
    cache_dir=".cache/catalogue",
)

# Suppress the download message
catalogue = Catalogue.load(silent=True)

Long-running processes

catalogue = Catalogue.load()
catalogue.digest     # sha256 of the loaded data.zip (None for a folder)
catalogue.loaded_at  # when it was loaded

# Call as often as you like (e.g. daily): returns the same object until max_age
# elapsed and the published archive actually changed, then a freshly loaded one.
catalogue = catalogue.maybe_refresh()

# Check now, regardless of max_age
catalogue = catalogue.refresh()

Network errors never raise from maybe_refresh() / refresh(); the last good copy stays.

Lookups

catalogue.asset_for('hyperliquid', 150)        # 'hyperliquid'  (spot token index)
catalogue.asset_for('arbitrum', '0xaf88d065e77c8cc2239327c5edb3a432268e5831')  # 'usd-coin' (any casing)
catalogue.asset_for('ethereum', 'native')      # 'ethereum'
catalogue.asset_for('bitget', 'rSPY')          # symbols are case-sensitive
catalogue.asset_for('mexc', 'UNKNOWN')         # None

catalogue.perpetual_for('hyperliquid', 'kPEPE')
# PerpetualInstrument(platform='hyperliquid', id='kPEPE', base='pepe', quote='tether',
#                     settlement='usd-coin', multiplier=Decimal('1000'), delisted=False)

catalogue.debt_for('ethereum', '0x72e95b8931767c79ba4eee721354d6e99a61d004')
# DebtInstrument(platform='ethereum', id='0x72E95b89…', asset='usd-coin', name='Aave USDC Debt')

catalogue.network_for('bybit', 'BSC (BEP20)')  # 'bnb-chain'
catalogue.canonical_id('old-id')               # follows `replaced_by` aliases

Every lookup follows replaced_by: asset ids are never deleted, and a merged asset keeps its file as an alias of the surviving one.

Correlation keys

A correlation key is a string both sides of one cross-chain movement can compute independently, e.g. a CCTP burn and its mint. Each key's namespace is a protocol in data/protocols/, which defines the key template and its typed fields, so two writers that never import each other produce the same string.

catalogue.format_correlation('cctp', source_domain=4, nonce=12345)  # 'cctp:4:12345'
catalogue.parse_correlation('ibc:dydx:channel-0:42')
# ('ibc', {'sending_chain': 'dydx', 'channel': 'channel-0', 'sequence': 42})

catalogue.network_for_domain('cctp', 3)           # 'arbitrum'
catalogue.domain_for_network('cctp', 'noble')     # 4
catalogue.protocol('hlbridge')                    # Protocol record, or None

Both raise CorrelationError (a ValueError) for an unknown namespace, missing or extra fields, or a value of the wrong type. Field types fix the canonical form: int/uint in base 10, hex as lower-case 0x… (bytes accepted), string as-is without : or whitespace, and network as an existing catalogue platform id.

A protocol that assigns each user its own deposit address (Hyperunit) publishes no address list. Its entry declares a deposits lookup instead: a public GET URL template with an {address} placeholder, the response field holding the operations, and the names of each operation's fields (deposit_address, sender, source_chain, destination_chain, destination_address, asset, optionally time). The protocol's chains and assets map its names to catalogue ids. A unit may keep the lookup's response as evidence for recognising a send to a deposit address; it never supplies a correlation key field.

catalogue.network_for_chain('hyperunit', 'ethereum')   # 'ethereum'
catalogue.asset_for_protocol('hyperunit', 'eth')       # 'ethereum'
catalogue.protocol('hyperunit')['deposits']['url']     # 'https://api.hyperunit.xyz/operations/{address}'

What's available

catalogue.assets           # dict[str, Asset]
catalogue.platforms        # dict[str, Platform]
catalogue.blockchains      # filtered view: kind == 'blockchain'
catalogue.cexs             # filtered view: kind == 'cex'
catalogue.dexs             # filtered view: kind == 'dex'

catalogue.spot_instruments        # dict[platform, dict[id, Spot]]
catalogue.perpetual_instruments   # dict[platform, dict[id, Perpetual]]
catalogue.debt_instruments        # dict[platform, dict[id, Debt]]
catalogue.pools                   # dict[platform, dict[id, Pool]]

catalogue.asset_translations      # dict[platform, dict[exchange_id, asset_id]]
catalogue.network_translations    # dict[platform, dict[exchange_id, network_id]]

catalogue.spam                    # dict[platform, dict[address, SpamAddress]]

catalogue.protocols               # dict[protocol, Protocol]

Types

All types are available from the package root:

from tribulnation.catalogue import (
    Asset, AssetPeg, ExternalIds,
    Platform, Blockchain, CexPlatform, DexPlatform,
    Spot, Perpetual, PerpetualInstrument, DebtInstrument, Debt, Pool,
    SpamAddress, Protocol, Correlation, CorrelationFieldType, CorrelationError,
)

Links

• Full catalogue & API
• GitHub
• JavaScript package