@defillama/sdk 5.0.235 → 5.0.236

package/build/chains/cardano.d.ts

@@ -0,0 +1,242 @@
+export declare const DEFAULT_ENDPOINT = "https://cardano-mainnet.blockfrost.io/api/v0";
+/** Blockfrost hard limit for `count` */
+export declare const MAX_PAGE_SIZE = 100;
+/**
+ * Shelley era (mainnet) started at slot 4492800 / unix 1596059091 with 1s slots, so
+ * `slot = timestamp - SHELLEY_SLOT_OFFSET`. Byron blocks (before that) use 20s slots and
+ * are not covered by the formula.
+ */
+export declare const SHELLEY_START_TIME = 1596059091;
+export declare const SHELLEY_START_SLOT = 4492800;
+export declare const SHELLEY_SLOT_OFFSET: number;
+/** Base url list: `CARDANO_BLOCKFROST` env (comma separated) wins, then `DEFAULT_ENDPOINT`. */
+export declare function getEndpointList(): string[];
+/** First configured base url. */
+export declare function getEndpoint(): string;
+/** Blockfrost project id from `BLOCKFROST_PROJECT_ID`; throws when unset. */
+export declare function getProjectId(): string;
+export interface AssetAmount {
+    /** `lovelace` or `<policyId><assetNameHex>` */
+    unit: string;
+    quantity: string;
+}
+export interface AddressInfo {
+    address: string;
+    amount: AssetAmount[];
+    stake_address: string | null;
+    type: string;
+    script: boolean;
+}
+export interface Utxo {
+    address: string;
+    tx_hash: string;
+    output_index: number;
+    amount: AssetAmount[];
+    block: string;
+    data_hash: string | null;
+    inline_datum: string | null;
+    reference_script_hash: string | null;
+}
+export interface AddressTransaction {
+    tx_hash: string;
+    tx_index: number;
+    block_height: number;
+    block_time: number;
+}
+export interface TxUtxos {
+    hash: string;
+    inputs: (Utxo & {
+        collateral: boolean;
+        reference: boolean;
+    })[];
+    outputs: (Utxo & {
+        collateral: boolean;
+        consumed_by_tx?: string | null;
+    })[];
+}
+export interface Asset {
+    asset: string;
+    policy_id: string;
+    asset_name: string | null;
+    fingerprint: string;
+    quantity: string;
+    initial_mint_tx_hash: string;
+    mint_or_burn_count: number;
+    onchain_metadata: Record<string, any> | null;
+    onchain_metadata_standard?: string | null;
+    metadata: {
+        name?: string;
+        description?: string;
+        ticker?: string | null;
+        url?: string | null;
+        logo?: string | null;
+        decimals?: number | null;
+    } | null;
+}
+export interface Block {
+    /** block height */
+    number: number;
+    /** unix seconds */
+    timestamp: number;
+    hash: string;
+    slot: number;
+    epoch: number;
+    /** raw Blockfrost block record */
+    raw: any;
+}
+export interface BlockfrostOptions {
+    /** path relative to the api root, e.g. `/addresses/addr1...` */
+    path: string;
+    params?: Record<string, any>;
+    /** return `null` on 404 instead of throwing */
+    allowNotFound?: boolean;
+    timeout?: number;
+    retries?: number;
+}
+export interface PagedOptions {
+    path: string;
+    params?: Record<string, any>;
+    /** page size, max 100 (Blockfrost limit) */
+    count?: number;
+    /** stop after this many pages (safety cap) */
+    maxPages?: number;
+}
+/**
+ * GET `path` from Blockfrost. Rotates through configured base urls, retries transient
+ * failures (5xx / 429) and, when `allowNotFound`, turns a 404 into `null` before the retry
+ * layer sees it.
+ */
+export declare function blockfrost({ path, params, allowNotFound, timeout, retries }: BlockfrostOptions): Promise<any>;
+/**
+ * Walk every page of a list endpoint (`count` per page, `page` 1..n) and concatenate the
+ * results. Stops on the first short / empty page or after `maxPages`.
+ */
+export declare function blockfrostAll<T = any>({ path, params, count, maxPages }: PagedOptions): Promise<T[]>;
+/** `/addresses/{address}`: balances (`amount`), stake address, type. `null` for unused addresses (404). */
+export declare function getAddress({ address }: {
+    address: string;
+}): Promise<AddressInfo | null>;
+/** All assets held by `address` as `{ unit, quantity }[]` (`lovelace` included). Empty for unused addresses. */
+export declare function getAddressAssets({ address }: {
+    address: string;
+}): Promise<AssetAmount[]>;
+/** ADA balance of `address` in lovelace (string). `'0'` for unused addresses. */
+export declare function getAdaBalance({ address }: {
+    address: string;
+}): Promise<string>;
+/** Balance of `asset` (`<policyId><assetNameHex>` or `lovelace`) held by `address`, as a string. */
+export declare function getTokenBalance({ address, asset }: {
+    address: string;
+    asset: string;
+}): Promise<string>;
+/** Every utxo at `address` (all pages). */
+export declare function getAddressUtxos({ address, maxPages }: {
+    address: string;
+    maxPages?: number;
+}): Promise<Utxo[]>;
+/** Every utxo at `address` containing `asset` (all pages). */
+export declare function getAddressUtxosByAsset({ address, asset, maxPages }: {
+    address: string;
+    asset: string;
+    maxPages?: number;
+}): Promise<Utxo[]>;
+/**
+ * Transactions involving `address` (all pages). `from` / `to` are block heights or
+ * `height:txIndex` strings, inclusive, as accepted by Blockfrost. `order` defaults to `asc`.
+ */
+export declare function getAddressTransactions({ address, from, to, order, maxPages }: {
+    address: string;
+    from?: number | string;
+    to?: number | string;
+    order?: 'asc' | 'desc';
+    maxPages?: number;
+}): Promise<AddressTransaction[]>;
+/** `/txs/{hash}/utxos`: inputs and outputs of a transaction. */
+export declare function getTxUtxos({ txHash }: {
+    txHash: string;
+}): Promise<TxUtxos>;
+/** `/txs/{hash}/redeemers` */
+export declare function getTxRedeemers({ txHash }: {
+    txHash: string;
+}): Promise<any[]>;
+/** `/txs/{hash}/metadata` */
+export declare function getTxMetadata({ txHash }: {
+    txHash: string;
+}): Promise<any[]>;
+/** `/scripts/datum/{hash}`: `{ json_value }`, or `null` when unknown. */
+export declare function getScriptDatum({ datumHash }: {
+    datumHash: string;
+}): Promise<{
+    json_value: any;
+} | null>;
+/** `/assets/{assetId}` record, or `null` when the asset was never minted. */
+export declare function getAsset({ assetId }: {
+    assetId: string;
+}): Promise<Asset | null>;
+/**
+ * Circulating supply (`quantity`, string) and decimals of an asset. Decimals come from the
+ * off-chain token registry (`metadata.decimals`) or CIP-68 on-chain metadata
+ * (`onchain_metadata.decimals`); `undefined` when neither is set.
+ */
+export declare function getAssetSupply({ assetId }: {
+    assetId: string;
+}): Promise<{
+    supply: string;
+    decimals: number | undefined;
+}>;
+export declare function getAssetDecimals(asset: Asset | null | undefined): number | undefined;
+/** `/assets/{assetId}/addresses`: every `{ address, quantity }` holding the asset (all pages). */
+export declare function getAssetAddresses({ assetId, maxPages }: {
+    assetId: string;
+    maxPages?: number;
+}): Promise<{
+    address: string;
+    quantity: string;
+}[]>;
+/** `/accounts/{stakeAddress}/addresses`: every payment address controlled by a stake key (all pages). */
+export declare function getAccountAddresses({ stakeAddress, maxPages }: {
+    stakeAddress: string;
+    maxPages?: number;
+}): Promise<string[]>;
+/** `/blocks/latest` as `{ number, timestamp, hash, slot, epoch, raw }`. */
+export declare function getLatestBlock(): Promise<Block>;
+/** `/blocks/{hashOrNumber}`; `null` when unknown. */
+export declare function getBlock({ hashOrNumber }: {
+    hashOrNumber: string | number;
+}): Promise<Block | null>;
+/** `/blocks/slot/{slot}`; `null` when no block was minted in that slot. */
+export declare function getBlockBySlot({ slot }: {
+    slot: number;
+}): Promise<Block | null>;
+/**
+ * Last block with `time <= timestamp` (unix seconds). For Shelley-era timestamps the slot is
+ * derived directly (`slot = timestamp - SHELLEY_SLOT_OFFSET`) and `/blocks/slot/{slot}` is
+ * tried first; otherwise (or when that slot is empty) an interpolation search over block
+ * heights, seeded from the latest block, converges in a handful of requests.
+ */
+export declare function getBlockAtTimestamp({ timestamp }: {
+    timestamp: number;
+}): Promise<Block>;
+/** `/epochs/{epoch}` (or `/epochs/latest`). */
+export declare function getEpoch({ epoch }?: {
+    epoch?: number | 'latest';
+}): Promise<any>;
+export interface ParsedAssetId {
+    policyId: string;
+    assetNameHex: string;
+    /** utf8 decoded asset name when it is printable ascii/utf8, otherwise the hex */
+    assetName: string;
+}
+/** Split `<policyId><assetNameHex>` (or `lovelace`) into its parts. */
+export declare function parseAssetId(assetId: string): ParsedAssetId;
+/** Hex asset name -> utf8 when it round-trips and is printable, else the hex itself. */
+export declare function decodeAssetName(assetNameHex: string): string;
+/**
+ * `policyId + assetNameHex`. `assetName` is taken as hex when it is a valid even-length hex
+ * string, otherwise utf8 encoded; pass `encoding` to force one.
+ */
+export declare function buildAssetId(policyId: string, assetName?: string, encoding?: 'hex' | 'utf8'): string;
+/** `stake1...` (mainnet) / `stake_test1...` bech32 reward addresses. */
+export declare function isStakeAddress(address: string): boolean;
+/** lovelace (string | number | bigint) -> ADA as a number. */
+export declare function lovelaceToAda(lovelace: string | number | bigint): number;

package/build/chains/cardano.js

@@ -0,0 +1,407 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHELLEY_SLOT_OFFSET = exports.SHELLEY_START_SLOT = exports.SHELLEY_START_TIME = exports.MAX_PAGE_SIZE = exports.DEFAULT_ENDPOINT = void 0;
+exports.getEndpointList = getEndpointList;
+exports.getEndpoint = getEndpoint;
+exports.getProjectId = getProjectId;
+exports.blockfrost = blockfrost;
+exports.blockfrostAll = blockfrostAll;
+exports.getAddress = getAddress;
+exports.getAddressAssets = getAddressAssets;
+exports.getAdaBalance = getAdaBalance;
+exports.getTokenBalance = getTokenBalance;
+exports.getAddressUtxos = getAddressUtxos;
+exports.getAddressUtxosByAsset = getAddressUtxosByAsset;
+exports.getAddressTransactions = getAddressTransactions;
+exports.getTxUtxos = getTxUtxos;
+exports.getTxRedeemers = getTxRedeemers;
+exports.getTxMetadata = getTxMetadata;
+exports.getScriptDatum = getScriptDatum;
+exports.getAsset = getAsset;
+exports.getAssetSupply = getAssetSupply;
+exports.getAssetDecimals = getAssetDecimals;
+exports.getAssetAddresses = getAssetAddresses;
+exports.getAccountAddresses = getAccountAddresses;
+exports.getLatestBlock = getLatestBlock;
+exports.getBlock = getBlock;
+exports.getBlockBySlot = getBlockBySlot;
+exports.getBlockAtTimestamp = getBlockAtTimestamp;
+exports.getEpoch = getEpoch;
+exports.parseAssetId = parseAssetId;
+exports.decodeAssetName = decodeAssetName;
+exports.buildAssetId = buildAssetId;
+exports.isStakeAddress = isStakeAddress;
+exports.lovelaceToAda = lovelaceToAda;
+/**
+ * Cardano client over the Blockfrost REST API (mainnet by default).
+ *
+ * Replaces the chain access parts of:
+ *   - DefiLlama-Adapters  projects/helper/chain/cardano/blockfrost.js (getAssets, getAddressesUTXOs,
+ *     getTxUtxos, getTxsRedeemers, getTxsMetadata, assetsAddresses, addressesUtxosAssetAll,
+ *     getTokensMinted, getScriptsDatum, getAccountAddresses)
+ *   - DefiLlama-Adapters  projects/helper/chain/cardano.js (getAda, getAdaInAddress, getTokenBalance)
+ *   - peggedassets-server src/adapters/peggedAssets/helper/cardano.ts (getAsset, getTotalSupply,
+ *     getTokenBalance, addressesUtxosAssetAll, getScriptsDatum)
+ *   - dimension-adapters  helpers/cardano.ts (blockfrost(path), getAdaReceived -> address transactions
+ *     in a time window + tx utxos)
+ *   - defillama-server    coins/src/adapters/markets/minswap.ts (Blockfrost axios client shape)
+ *
+ * TVL coupling (sumTokens / Balances / Minswap GraphQL pricing) is intentionally left out;
+ * every function returns raw chain values (lovelace / asset quantities as strings).
+ *
+ * Configuration:
+ *   - `BLOCKFROST_PROJECT_ID` (required, also `SDK_` / `LLAMA_SDK_` prefixed): Blockfrost api key.
+ *     No key is embedded in the sdk.
+ *   - `CARDANO_BLOCKFROST` (optional, comma separated): api base url(s), default
+ *     `https://cardano-mainnet.blockfrost.io/api/v0`.
+ *   - `CARDANO_RPC_CONCURRENCY` (optional): max parallel requests, default 5.
+ *
+ * Usage: `sdk.chains.cardano.getAdaBalance({ address })`
+ */
+const axios_1 = __importDefault(require("axios"));
+const env_1 = require("../util/env");
+const debugLog_1 = require("../util/debugLog");
+const rpc_1 = require("./rpc");
+// ---------------------------------------------------------------------------
+// config
+// ---------------------------------------------------------------------------
+exports.DEFAULT_ENDPOINT = "https://cardano-mainnet.blockfrost.io/api/v0";
+const ENDPOINT_ENV_KEY = 'CARDANO_BLOCKFROST';
+const PROJECT_ID_ENV_KEY = 'BLOCKFROST_PROJECT_ID';
+const LIMITER_KEY = 'cardano';
+const CONCURRENCY = 5;
+const DEFAULT_TIMEOUT = 120000;
+/** Blockfrost hard limit for `count` */
+exports.MAX_PAGE_SIZE = 100;
+/**
+ * Shelley era (mainnet) started at slot 4492800 / unix 1596059091 with 1s slots, so
+ * `slot = timestamp - SHELLEY_SLOT_OFFSET`. Byron blocks (before that) use 20s slots and
+ * are not covered by the formula.
+ */
+exports.SHELLEY_START_TIME = 1596059091;
+exports.SHELLEY_START_SLOT = 4492800;
+exports.SHELLEY_SLOT_OFFSET = exports.SHELLEY_START_TIME - exports.SHELLEY_START_SLOT; // 1591566291
+/** Base url list: `CARDANO_BLOCKFROST` env (comma separated) wins, then `DEFAULT_ENDPOINT`. */
+function getEndpointList() {
+    return (0, rpc_1.getEndpoints)('cardano', exports.DEFAULT_ENDPOINT, { envKey: ENDPOINT_ENV_KEY });
+}
+/** First configured base url. */
+function getEndpoint() {
+    return getEndpointList()[0];
+}
+/** Blockfrost project id from `BLOCKFROST_PROJECT_ID`; throws when unset. */
+function getProjectId() {
+    const value = (0, env_1.getEnvValue)(PROJECT_ID_ENV_KEY);
+    if (!value)
+        throw new Error(`[chains.cardano] missing Blockfrost api key: set the ${PROJECT_ID_ENV_KEY} env var (https://blockfrost.io)`);
+    return value;
+}
+// ---------------------------------------------------------------------------
+// client
+// ---------------------------------------------------------------------------
+const NOT_FOUND = Symbol('not-found');
+function isNotFound(e) {
+    var _a;
+    return ((_a = e === null || e === void 0 ? void 0 : e.response) === null || _a === void 0 ? void 0 : _a.status) === 404;
+}
+/**
+ * GET `path` from Blockfrost. Rotates through configured base urls, retries transient
+ * failures (5xx / 429) and, when `allowNotFound`, turns a 404 into `null` before the retry
+ * layer sees it.
+ */
+async function blockfrost({ path, params, allowNotFound = false, timeout = DEFAULT_TIMEOUT, retries }) {
+    const endpoints = getEndpointList();
+    const headers = { project_id: getProjectId(), 'Content-Type': 'application/json' };
+    const config = { timeout, headers, params };
+    const limiter = (0, rpc_1.getLimiter)(LIMITER_KEY, CONCURRENCY);
+    const res = await (0, rpc_1.withRetry)(async (attempt) => {
+        const base = endpoints[attempt % endpoints.length];
+        const url = (0, rpc_1.joinUrl)(base, path);
+        return limiter(async () => {
+            var _a, _b, _c, _d, _e, _f, _g;
+            try {
+                const response = await axios_1.default.get(url, config);
+                return response.data;
+            }
+            catch (e) {
+                if (allowNotFound && isNotFound(e)) {
+                    (0, debugLog_1.debugLog)(`[chains.cardano] GET ${path} -> 404 (treated as not found)`);
+                    return NOT_FOUND;
+                }
+                const status = (_a = e === null || e === void 0 ? void 0 : e.response) === null || _a === void 0 ? void 0 : _a.status;
+                const detail = (_g = (_d = (_c = (_b = e === null || e === void 0 ? void 0 : e.response) === null || _b === void 0 ? void 0 : _b.data) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : (_f = (_e = e === null || e === void 0 ? void 0 : e.response) === null || _e === void 0 ? void 0 : _e.data) === null || _f === void 0 ? void 0 : _f.error) !== null && _g !== void 0 ? _g : e === null || e === void 0 ? void 0 : e.message;
+                const err = new Error(`[cardano] GET ${path} failed${status ? ` [${status}]` : ''}: ${String(detail !== null && detail !== void 0 ? detail : '').slice(0, 300)} (${(0, rpc_1.shortUrl)(url)})`);
+                err.response = e === null || e === void 0 ? void 0 : e.response;
+                err.status = status;
+                throw err;
+            }
+        });
+    }, {
+        label: `cardano GET ${path.split('?')[0].slice(0, 80)}`,
+        retries: retries !== null && retries !== void 0 ? retries : Math.max(3, endpoints.length),
+        shouldRetry: rpc_1.isRetryableError,
+    });
+    return res === NOT_FOUND ? null : res;
+}
+/**
+ * Walk every page of a list endpoint (`count` per page, `page` 1..n) and concatenate the
+ * results. Stops on the first short / empty page or after `maxPages`.
+ */
+async function blockfrostAll({ path, params, count = exports.MAX_PAGE_SIZE, maxPages }) {
+    if (count < 1 || count > exports.MAX_PAGE_SIZE)
+        throw new Error(`[chains.cardano] blockfrostAll: count must be between 1 and ${exports.MAX_PAGE_SIZE}`);
+    const results = [];
+    let page = 1;
+    while (true) {
+        const res = await blockfrost({ path, params: { ...(params !== null && params !== void 0 ? params : {}), count, page } });
+        if (!Array.isArray(res))
+            throw new Error(`[chains.cardano] GET ${path}: expected an array on page ${page}`);
+        results.push(...res);
+        if (res.length < count)
+            break;
+        if (maxPages !== undefined && page >= maxPages) {
+            (0, debugLog_1.debugLog)(`[chains.cardano] GET ${path}: stopped after maxPages=${maxPages}, result may be truncated`);
+            break;
+        }
+        page++;
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// addresses
+// ---------------------------------------------------------------------------
+/** `/addresses/{address}`: balances (`amount`), stake address, type. `null` for unused addresses (404). */
+async function getAddress({ address }) {
+    return blockfrost({ path: `/addresses/${address}`, allowNotFound: true });
+}
+/** All assets held by `address` as `{ unit, quantity }[]` (`lovelace` included). Empty for unused addresses. */
+async function getAddressAssets({ address }) {
+    var _a;
+    const info = await getAddress({ address });
+    return (_a = info === null || info === void 0 ? void 0 : info.amount) !== null && _a !== void 0 ? _a : [];
+}
+/** ADA balance of `address` in lovelace (string). `'0'` for unused addresses. */
+async function getAdaBalance({ address }) {
+    return getTokenBalance({ address, asset: 'lovelace' });
+}
+/** Balance of `asset` (`<policyId><assetNameHex>` or `lovelace`) held by `address`, as a string. */
+async function getTokenBalance({ address, asset }) {
+    var _a, _b;
+    const assets = await getAddressAssets({ address });
+    return (_b = (_a = assets.find(i => i.unit === asset)) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0';
+}
+/** Every utxo at `address` (all pages). */
+async function getAddressUtxos({ address, maxPages }) {
+    return blockfrostAll({ path: `/addresses/${address}/utxos`, maxPages });
+}
+/** Every utxo at `address` containing `asset` (all pages). */
+async function getAddressUtxosByAsset({ address, asset, maxPages }) {
+    return blockfrostAll({ path: `/addresses/${address}/utxos/${asset}`, maxPages });
+}
+/**
+ * Transactions involving `address` (all pages). `from` / `to` are block heights or
+ * `height:txIndex` strings, inclusive, as accepted by Blockfrost. `order` defaults to `asc`.
+ */
+async function getAddressTransactions({ address, from, to, order, maxPages }) {
+    const params = {};
+    if (from !== undefined)
+        params.from = String(from);
+    if (to !== undefined)
+        params.to = String(to);
+    if (order)
+        params.order = order;
+    return blockfrostAll({ path: `/addresses/${address}/transactions`, params, maxPages });
+}
+// ---------------------------------------------------------------------------
+// transactions / scripts
+// ---------------------------------------------------------------------------
+/** `/txs/{hash}/utxos`: inputs and outputs of a transaction. */
+async function getTxUtxos({ txHash }) {
+    return blockfrost({ path: `/txs/${txHash}/utxos` });
+}
+/** `/txs/{hash}/redeemers` */
+async function getTxRedeemers({ txHash }) {
+    return blockfrost({ path: `/txs/${txHash}/redeemers` });
+}
+/** `/txs/{hash}/metadata` */
+async function getTxMetadata({ txHash }) {
+    return blockfrost({ path: `/txs/${txHash}/metadata` });
+}
+/** `/scripts/datum/{hash}`: `{ json_value }`, or `null` when unknown. */
+async function getScriptDatum({ datumHash }) {
+    return blockfrost({ path: `/scripts/datum/${datumHash}`, allowNotFound: true });
+}
+// ---------------------------------------------------------------------------
+// assets
+// ---------------------------------------------------------------------------
+/** `/assets/{assetId}` record, or `null` when the asset was never minted. */
+async function getAsset({ assetId }) {
+    return blockfrost({ path: `/assets/${assetId}`, allowNotFound: true });
+}
+/**
+ * Circulating supply (`quantity`, string) and decimals of an asset. Decimals come from the
+ * off-chain token registry (`metadata.decimals`) or CIP-68 on-chain metadata
+ * (`onchain_metadata.decimals`); `undefined` when neither is set.
+ */
+async function getAssetSupply({ assetId }) {
+    var _a;
+    const asset = await getAsset({ assetId });
+    if (!asset)
+        throw new Error(`[chains.cardano] asset ${assetId} not found`);
+    return { supply: String((_a = asset.quantity) !== null && _a !== void 0 ? _a : '0'), decimals: getAssetDecimals(asset) };
+}
+function getAssetDecimals(asset) {
+    var _a, _b;
+    const candidates = [(_a = asset === null || asset === void 0 ? void 0 : asset.metadata) === null || _a === void 0 ? void 0 : _a.decimals, (_b = asset === null || asset === void 0 ? void 0 : asset.onchain_metadata) === null || _b === void 0 ? void 0 : _b.decimals];
+    for (const value of candidates) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        const n = Number(value);
+        if (Number.isInteger(n) && n >= 0)
+            return n;
+    }
+    return undefined;
+}
+/** `/assets/{assetId}/addresses`: every `{ address, quantity }` holding the asset (all pages). */
+async function getAssetAddresses({ assetId, maxPages }) {
+    return blockfrostAll({ path: `/assets/${assetId}/addresses`, maxPages });
+}
+// ---------------------------------------------------------------------------
+// accounts
+// ---------------------------------------------------------------------------
+/** `/accounts/{stakeAddress}/addresses`: every payment address controlled by a stake key (all pages). */
+async function getAccountAddresses({ stakeAddress, maxPages }) {
+    const rows = await blockfrostAll({ path: `/accounts/${stakeAddress}/addresses`, maxPages });
+    return rows.map(i => i.address);
+}
+// ---------------------------------------------------------------------------
+// blocks / epochs
+// ---------------------------------------------------------------------------
+function toBlock(raw) {
+    return { number: raw.height, timestamp: raw.time, hash: raw.hash, slot: raw.slot, epoch: raw.epoch, raw };
+}
+/** `/blocks/latest` as `{ number, timestamp, hash, slot, epoch, raw }`. */
+async function getLatestBlock() {
+    return toBlock(await blockfrost({ path: '/blocks/latest' }));
+}
+/** `/blocks/{hashOrNumber}`; `null` when unknown. */
+async function getBlock({ hashOrNumber }) {
+    const raw = await blockfrost({ path: `/blocks/${hashOrNumber}`, allowNotFound: true });
+    return raw ? toBlock(raw) : null;
+}
+/** `/blocks/slot/{slot}`; `null` when no block was minted in that slot. */
+async function getBlockBySlot({ slot }) {
+    const raw = await blockfrost({ path: `/blocks/slot/${slot}`, allowNotFound: true });
+    return raw ? toBlock(raw) : null;
+}
+/**
+ * Last block with `time <= timestamp` (unix seconds). For Shelley-era timestamps the slot is
+ * derived directly (`slot = timestamp - SHELLEY_SLOT_OFFSET`) and `/blocks/slot/{slot}` is
+ * tried first; otherwise (or when that slot is empty) an interpolation search over block
+ * heights, seeded from the latest block, converges in a handful of requests.
+ */
+async function getBlockAtTimestamp({ timestamp }) {
+    if (!timestamp || !Number.isFinite(timestamp))
+        throw new Error('[chains.cardano] getBlockAtTimestamp: invalid timestamp');
+    if (timestamp > 1e12)
+        timestamp = Math.floor(timestamp / 1000); // tolerate milliseconds
+    const latest = await getLatestBlock();
+    if (latest.timestamp <= timestamp)
+        return latest;
+    let steps = 0;
+    if (timestamp >= exports.SHELLEY_START_TIME) {
+        const exact = await getBlockBySlot({ slot: timestamp - exports.SHELLEY_SLOT_OFFSET });
+        steps++;
+        if (exact && exact.timestamp === timestamp) {
+            (0, debugLog_1.debugLog)(`[chains.cardano] getBlockAtTimestamp(${timestamp}) -> block ${exact.number} via slot lookup`);
+            return exact;
+        }
+    }
+    const cache = new Map();
+    cache.set(latest.number, latest);
+    const fetchBlock = async (height) => {
+        if (!cache.has(height)) {
+            const block = await getBlock({ hashOrNumber: height });
+            if (!block)
+                throw new Error(`[chains.cardano] block ${height} not found`);
+            cache.set(height, block);
+            steps++;
+        }
+        return cache.get(height);
+    };
+    let hi = latest;
+    let lo = await fetchBlock(1);
+    if (lo.timestamp > timestamp)
+        throw new Error(`[chains.cardano] timestamp ${timestamp} predates the chain (block 1 at ${lo.timestamp})`);
+    // invariant: lo.timestamp <= timestamp < hi.timestamp
+    while (hi.number - lo.number > 1) {
+        const span = hi.timestamp - lo.timestamp;
+        let guess = span > 0
+            ? lo.number + Math.floor((hi.number - lo.number) * (timestamp - lo.timestamp) / span)
+            : Math.floor((lo.number + hi.number) / 2);
+        // keep the guess strictly inside (lo, hi); alternate with bisection when interpolation stalls
+        if (guess <= lo.number || guess >= hi.number || steps % 4 === 3)
+            guess = Math.floor((lo.number + hi.number) / 2);
+        const block = await fetchBlock(guess);
+        if (block.timestamp <= timestamp)
+            lo = block;
+        else
+            hi = block;
+        if (steps > 200)
+            throw new Error(`[chains.cardano] getBlockAtTimestamp(${timestamp}): search did not converge`);
+    }
+    (0, debugLog_1.debugLog)(`[chains.cardano] getBlockAtTimestamp(${timestamp}) -> block ${lo.number} in ${steps} requests`);
+    return lo;
+}
+/** `/epochs/{epoch}` (or `/epochs/latest`). */
+async function getEpoch({ epoch = 'latest' } = {}) {
+    return blockfrost({ path: `/epochs/${epoch}` });
+}
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+const POLICY_ID_LENGTH = 56;
+const HEX_RE = /^([0-9a-fA-F]{2})*$/;
+/** Split `<policyId><assetNameHex>` (or `lovelace`) into its parts. */
+function parseAssetId(assetId) {
+    if (assetId === 'lovelace')
+        return { policyId: '', assetNameHex: '', assetName: 'lovelace' };
+    if (typeof assetId !== 'string' || assetId.length < POLICY_ID_LENGTH || !HEX_RE.test(assetId))
+        throw new Error(`[chains.cardano] invalid asset id: ${assetId}`);
+    const policyId = assetId.slice(0, POLICY_ID_LENGTH).toLowerCase();
+    const assetNameHex = assetId.slice(POLICY_ID_LENGTH).toLowerCase();
+    return { policyId, assetNameHex, assetName: decodeAssetName(assetNameHex) };
+}
+/** Hex asset name -> utf8 when it round-trips and is printable, else the hex itself. */
+function decodeAssetName(assetNameHex) {
+    if (!assetNameHex)
+        return '';
+    const buf = Buffer.from(assetNameHex, 'hex');
+    const utf8 = buf.toString('utf8');
+    const roundTrips = Buffer.from(utf8, 'utf8').toString('hex') === assetNameHex.toLowerCase();
+    // printable: no control chars (0x00-0x1f, 0x7f) and no replacement char
+    const printable = roundTrips && !/[\u0000-\u001f\u007f�]/.test(utf8);
+    return printable ? utf8 : assetNameHex.toLowerCase();
+}
+/**
+ * `policyId + assetNameHex`. `assetName` is taken as hex when it is a valid even-length hex
+ * string, otherwise utf8 encoded; pass `encoding` to force one.
+ */
+function buildAssetId(policyId, assetName = '', encoding) {
+    if (typeof policyId !== 'string' || policyId.length !== POLICY_ID_LENGTH || !HEX_RE.test(policyId))
+        throw new Error(`[chains.cardano] invalid policy id: ${policyId}`);
+    const isHex = encoding === 'hex' || (encoding === undefined && HEX_RE.test(assetName));
+    const nameHex = isHex ? assetName.toLowerCase() : Buffer.from(assetName, 'utf8').toString('hex');
+    return policyId.toLowerCase() + nameHex;
+}
+/** `stake1...` (mainnet) / `stake_test1...` bech32 reward addresses. */
+function isStakeAddress(address) {
+    return typeof address === 'string' && /^stake(_test)?1[a-z0-9]+$/.test(address);
+}
+/** lovelace (string | number | bigint) -> ADA as a number. */
+function lovelaceToAda(lovelace) {
+    return Number(lovelace) / 1e6;
+}