@koralabs/kora-labs-common 6.16.0 → 6.18.0

package/chain/datum/cip68Metadata.d.ts

@@ -0,0 +1,15 @@
+export type Cip68Standard = 'ft' | 'nft' | 'rft';
+/** CIP-67 labels (with checksum) of the CIP-68 user tokens Blockfrost resolves, and of the reference NFT. */
+export declare const CIP68_REFERENCE_LABEL = "000643b0";
+/** For a CIP-68 user token (222/333/444) asset-name hex: its standard and reference-NFT asset-name hex. */
+export declare const cip68ReferenceOf: (hex: string) => {
+    standard: Cip68Standard;
+    referenceHex: string;
+} | null;
+/** Port of the UTF-8 validator Blockfrost uses (websockets/utf-8-validate fallback). */
+export declare const isValidUTF8: (buf: Buffer) => boolean;
+/**
+ * Blockfrost's `onchain_metadata` for a CIP-68 token whose reference NFT carries `datumHex`, or null
+ * when the datum is not a CIP-68 `Constr [metadata_map, version, extra?]`.
+ */
+export declare const cip68OnchainMetadata: (datumHex: string, standard: Cip68Standard) => Record<string, unknown> | null;

package/chain/datum/cip68Metadata.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cip68OnchainMetadata = exports.isValidUTF8 = exports.cip68ReferenceOf = exports.CIP68_REFERENCE_LABEL = void 0;
+// CIP-68 reference-datum -> `onchain_metadata`, exactly as Blockfrost reports it for `/assets/{unit}`.
+//
+// Ported from blockfrost-utils `src/cip68.ts` (getMetadataFromOutputDatum / convertDatumValue,
+// github.com/blockfrost/blockfrost-utils @ b467b2a). Providers without that endpoint (Koios) read the
+// reference token's datum and convert it here, so every consumer sees ONE metadata shape whichever
+// provider answered. Blockfrost's quirks are kept on purpose: only the CIP-68 schema fields of the
+// token's standard are decoded (bytes -> UTF-8, or hex when not valid UTF-8); every other field keeps
+// the value's ORIGINAL CBOR hex (consumers such as the HAL BFF decode those themselves).
+const cbor_1 = __importDefault(require("cbor"));
+const cbor_2 = require("../../tx/cbor");
+const FILES = {
+    type: 'array',
+    optional: true,
+    items: {
+        name: { type: 'bytestring', optional: true },
+        mediaType: { type: 'bytestring' },
+        src: { type: 'bytestring' }
+    }
+};
+const METADATA_SCHEME_MAP = {
+    ft: {
+        name: { type: 'bytestring' },
+        description: { type: 'bytestring' },
+        ticker: { type: 'bytestring', optional: true },
+        url: { type: 'bytestring', optional: true },
+        logo: { type: 'bytestring', optional: true },
+        decimals: { type: 'number', optional: true }
+    },
+    nft: {
+        name: { type: 'bytestring' },
+        image: { type: 'bytestring' },
+        mediaType: { type: 'bytestring', optional: true },
+        description: { type: 'bytestring', optional: true },
+        files: FILES
+    },
+    rft: {
+        name: { type: 'bytestring' },
+        image: { type: 'bytestring' },
+        mediaType: { type: 'bytestring', optional: true },
+        description: { type: 'bytestring', optional: true },
+        decimals: { type: 'number', optional: true },
+        files: FILES
+    }
+};
+/** CIP-67 labels (with checksum) of the CIP-68 user tokens Blockfrost resolves, and of the reference NFT. */
+exports.CIP68_REFERENCE_LABEL = '000643b0';
+const USER_TOKEN_STANDARDS = { '000de140': 'nft', '0014df10': 'ft', '001bc280': 'rft' };
+/** For a CIP-68 user token (222/333/444) asset-name hex: its standard and reference-NFT asset-name hex. */
+const cip68ReferenceOf = (hex) => {
+    const standard = USER_TOKEN_STANDARDS[hex.slice(0, 8)];
+    return standard ? { standard, referenceHex: `${exports.CIP68_REFERENCE_LABEL}${hex.slice(8)}` } : null;
+};
+exports.cip68ReferenceOf = cip68ReferenceOf;
+/** Port of the UTF-8 validator Blockfrost uses (websockets/utf-8-validate fallback). */
+const isValidUTF8 = (buf) => {
+    const len = buf.length;
+    let i = 0;
+    while (i < len) {
+        if ((buf[i] & 0x80) === 0x00) {
+            i++;
+        }
+        else if ((buf[i] & 0xe0) === 0xc0) {
+            if (i + 1 === len || (buf[i + 1] & 0xc0) !== 0x80 || (buf[i] & 0xfe) === 0xc0)
+                return false;
+            i += 2;
+        }
+        else if ((buf[i] & 0xf0) === 0xe0) {
+            if (i + 2 >= len ||
+                (buf[i + 1] & 0xc0) !== 0x80 ||
+                (buf[i + 2] & 0xc0) !== 0x80 ||
+                (buf[i] === 0xe0 && (buf[i + 1] & 0xe0) === 0x80) ||
+                (buf[i] === 0xed && (buf[i + 1] & 0xe0) === 0xa0)) {
+                return false;
+            }
+            i += 3;
+        }
+        else if ((buf[i] & 0xf8) === 0xf0) {
+            if (i + 3 >= len ||
+                (buf[i + 1] & 0xc0) !== 0x80 ||
+                (buf[i + 2] & 0xc0) !== 0x80 ||
+                (buf[i + 3] & 0xc0) !== 0x80 ||
+                (buf[i] === 0xf0 && (buf[i + 1] & 0xf0) === 0x80) ||
+                (buf[i] === 0xf4 && buf[i + 1] > 0x8f) ||
+                buf[i] > 0xf4) {
+                return false;
+            }
+            i += 4;
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+};
+exports.isValidUTF8 = isValidUTF8;
+const toUTF8OrHex = (buffer) => ((0, exports.isValidUTF8)(buffer) ? buffer.toString('utf8') : buffer.toString('hex'));
+const convertDatumValue = (decodedValue, schema) => {
+    var _a;
+    if (!schema)
+        return null;
+    const scheme = schema;
+    if (scheme.type === 'number' && typeof decodedValue === 'number')
+        return decodedValue;
+    if (scheme.type === 'bytestring' && Buffer.isBuffer(decodedValue))
+        return toUTF8OrHex(decodedValue);
+    if (scheme.type === 'bytestring' && Array.isArray(decodedValue))
+        return toUTF8OrHex(Buffer.concat(decodedValue));
+    if (Array.isArray(decodedValue)) {
+        const converted = [];
+        for (const item of decodedValue) {
+            const value = convertDatumValue(item, (_a = scheme.items) !== null && _a !== void 0 ? _a : null);
+            if (value === null)
+                return null;
+            converted.push(value);
+        }
+        return converted;
+    }
+    if (decodedValue instanceof Map) {
+        const metadataMap = {};
+        for (const [key, mapValue] of decodedValue.entries()) {
+            const convertedKey = Buffer.isBuffer(key) ? toUTF8OrHex(key) : key;
+            const valueSchema = schema && convertedKey in schema ? schema[convertedKey] : null;
+            const value = convertDatumValue(mapValue, valueSchema);
+            if (value === null)
+                return null;
+            metadataMap[convertedKey] = value;
+        }
+        return metadataMap;
+    }
+    return null;
+};
+/** Start/end of the constructor's fields list: `#6.121..127/1280..1400([fields])` or `#6.102([index, [fields]])`. */
+const constrFields = (bytes) => {
+    const tag = (0, cbor_2.readCborHeader)(bytes, 0);
+    if (tag.majorType !== 6)
+        return null;
+    const isCompact = (tag.length >= 121 && tag.length <= 127) || (tag.length >= 1280 && tag.length <= 1400);
+    if (isCompact)
+        return tag.headerEnd;
+    if (tag.length !== 102)
+        return null;
+    const pair = (0, cbor_2.readCborHeader)(bytes, tag.headerEnd);
+    return pair.majorType === 4 ? (0, cbor_2.skipCborItem)(bytes, pair.headerEnd) : null;
+};
+/** The CBOR items of the list starting at `start` (definite or indefinite), as [start, end) spans. */
+const listItems = (bytes, start) => {
+    const header = (0, cbor_2.readCborHeader)(bytes, start);
+    if (header.majorType !== 4)
+        return null;
+    const spans = [];
+    let cursor = header.headerEnd;
+    const indefinite = header.additionalInfo === 31;
+    for (let i = 0; indefinite ? bytes[cursor] !== 0xff : i < header.length; i++) {
+        const end = (0, cbor_2.skipCborItem)(bytes, cursor);
+        spans.push([cursor, end]);
+        cursor = end;
+    }
+    return spans;
+};
+/**
+ * Blockfrost's `onchain_metadata` for a CIP-68 token whose reference NFT carries `datumHex`, or null
+ * when the datum is not a CIP-68 `Constr [metadata_map, version, extra?]`.
+ */
+const cip68OnchainMetadata = (datumHex, standard) => {
+    const bytes = Buffer.from(datumHex, 'hex');
+    let fields;
+    try {
+        const fieldsStart = constrFields(bytes);
+        fields = fieldsStart === null ? null : listItems(bytes, fieldsStart);
+    }
+    catch (_a) {
+        return null;
+    }
+    // [metadata, version] are mandatory
+    if (!fields || fields.length < 2)
+        return null;
+    const [mapStart] = fields[0];
+    const map = (0, cbor_2.readCborHeader)(bytes, mapStart);
+    if (map.majorType !== 5)
+        return null;
+    const schema = METADATA_SCHEME_MAP[standard];
+    const metadata = {};
+    const seenKeys = new Set();
+    let cursor = map.headerEnd;
+    const indefinite = map.additionalInfo === 31;
+    for (let i = 0; indefinite ? bytes[cursor] !== 0xff : i < map.length; i++) {
+        const keyEnd = (0, cbor_2.skipCborItem)(bytes, cursor);
+        const valueEnd = (0, cbor_2.skipCborItem)(bytes, keyEnd);
+        const keyBytes = bytes.subarray(cursor, keyEnd);
+        const valueBytes = bytes.subarray(keyEnd, valueEnd);
+        cursor = valueEnd;
+        // CSL's PlutusMap groups a repeated key's values and Blockfrost reads the first one.
+        const keyId = keyBytes.toString('hex');
+        if (seenKeys.has(keyId))
+            continue;
+        seenKeys.add(keyId);
+        const decodedKey = cbor_1.default.decodeFirstSync(keyBytes);
+        const convertedKey = Buffer.isBuffer(decodedKey) ? toUTF8OrHex(decodedKey) : decodedKey;
+        const valueHex = valueBytes.toString('hex');
+        if (!(schema && convertedKey in schema)) {
+            // Custom field not covered by the CIP-68 standard: unparsed CBOR
+            metadata[convertedKey] = valueHex;
+        }
+        else {
+            const converted = convertDatumValue(cbor_1.default.decodeFirstSync(valueBytes), schema[convertedKey]);
+            metadata[convertedKey] = converted !== null ? converted : valueHex;
+        }
+    }
+    return metadata;
+};
+exports.cip68OnchainMetadata = cip68OnchainMetadata;

package/chain/failover/ChainProviderFailover.d.ts

@@ -1,4 +1,4 @@
-import { AccountAsset, AddressInfo, BackgroundImageDetails, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from './interfaces';
+import { AccountAsset, AddressInfo, BackgroundImageDetails, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from './interfaces';
 export interface FailoverOptions {
     /**
      * Cooldown (ms) during which a provider that just failed is skipped as the *start* provider,
@@ -42,9 +42,14 @@ export declare class ChainProviderFailover {
     getRefScriptCbor(tx: string, policyId: string, hex: string): Promise<string>;
     getTxUtxos(tx: string): Promise<ChainProviderUtxo>;
     getAssetUtxo(policyId: string, hex: string): Promise<ChainProviderAsset | null>;
+    /** Index of the Blockfrost provider, if configured (start provider for freshness-critical reads). */
+    private blockfrostIndex;
     getAssetsByStakeKey(stakeKey: string): Promise<AccountAsset[]>;
     getDatumFromHash(datumHash: string): Promise<string | null>;
     getBackgroundImageDetails(policyId: string, hex: string): Promise<BackgroundImageDetails>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }

package/chain/failover/ChainProviderFailover.js

@@ -29,18 +29,22 @@ class ChainProviderFailover {
     getNextProviderIndex(currentIndex) {
         return (currentIndex + 1) % this.providers.length;
     }
-    async getResponse(funcName, args, currentIndex, runNum) {
+    async getResponse(funcName, args, currentIndex, runNum, notFound) {
         const num = runNum !== null && runNum !== void 0 ? runNum : 0;
         const index = currentIndex !== null && currentIndex !== void 0 ? currentIndex : this.getStartIndex();
         const chainProvider = this.providers[index];
         return await chainProvider[funcName](...args).catch((error) => {
+            // A 404 is an answer ("not on chain (yet)"), not a provider failure: it still falls
+            // through, but without benching the provider, and it outranks another provider's outage.
+            const isNotFound = (error === null || error === void 0 ? void 0 : error.status) === 404;
             // Mark the failed provider unhealthy for the cooldown window so it isn't chosen as the
             // start provider again immediately; it remains a valid fallback.
-            if (this.cooldownMs > 0)
+            if (this.cooldownMs > 0 && !isNotFound)
                 this.unhealthyUntil[index] = this.now() + this.cooldownMs;
+            const answer = notFound !== null && notFound !== void 0 ? notFound : (isNotFound ? error : undefined);
             if (num === this.providers.length - 1)
-                throw error;
-            return this.getResponse(funcName, args, this.getNextProviderIndex(index), num + 1);
+                throw answer !== null && answer !== void 0 ? answer : error;
+            return this.getResponse(funcName, args, this.getNextProviderIndex(index), num + 1, answer);
         });
     }
     async getLatestTransactionForAsset(policyId, hex) {
@@ -69,8 +73,12 @@ class ChainProviderFailover {
         // provider lagging a burn returns a stale UTxO and falsely resurrects a de-indexed handle.
         // Prefer Blockfrost (reads the latest asset tx live; Koios's tx index can lag a burn by
         // minutes). Koios stays the failover on error.
-        const preferredIndex = this.providers.findIndex((p) => { var _a; return ((_a = p.name) !== null && _a !== void 0 ? _a : '').toLowerCase().includes('blockfrost'); });
-        return this.getResponse('getAssetUtxo', [policyId, hex], preferredIndex >= 0 ? preferredIndex : undefined);
+        return this.getResponse('getAssetUtxo', [policyId, hex], this.blockfrostIndex());
+    }
+    /** Index of the Blockfrost provider, if configured (start provider for freshness-critical reads). */
+    blockfrostIndex() {
+        const index = this.providers.findIndex((p) => { var _a; return ((_a = p.name) !== null && _a !== void 0 ? _a : '').toLowerCase().includes('blockfrost'); });
+        return index >= 0 ? index : undefined;
     }
     async getAssetsByStakeKey(stakeKey) {
         return this.getResponse('getAssetsByStakeKey', [stakeKey]);
@@ -87,5 +95,15 @@ class ChainProviderFailover {
     async getAddressUTxOs(bech32Address) {
         return this.getResponse('getAddressUTxOs', [bech32Address]);
     }
+    async getProtocolParameters() {
+        return this.getResponse('getProtocolParameters', []);
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        // Blockfrost answers from its spent-by index in one call; Koios has to scan the address's txs.
+        return this.getResponse('getTxOutputConsumer', [txHash, outputIndex], this.blockfrostIndex());
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        return this.getResponse('getAssetOnchainMetadata', [policyId, hex]);
+    }
 }
 exports.ChainProviderFailover = ChainProviderFailover;

package/chain/failover/interfaces.d.ts

@@ -28,6 +28,26 @@ export interface AddressInfo {
     stake_address?: string | null;
     script: boolean;
 }
+/**
+ * Current protocol parameters in Blockfrost's `/epochs/latest/parameters` field names (Koios's
+ * `/epoch_params` uses the same names and reports identical values; its `cost_models` is mapped to
+ * `cost_models_raw`). Cost models are ledger-ordered arrays keyed `PlutusV1`/`PlutusV2`/`PlutusV3`.
+ * `@koralabs/kora-labs-common/txBuild` `protocolParametersFromChain` turns this into tx-builder params.
+ */
+export interface ChainProtocolParameters {
+    epoch: number;
+    min_fee_a: number;
+    min_fee_b: number;
+    max_tx_size: number;
+    coins_per_utxo_size: string;
+    key_deposit: string;
+    price_mem: number;
+    price_step: number;
+    max_tx_ex_mem: string;
+    max_tx_ex_steps: string;
+    min_fee_ref_script_cost_per_byte: number | null;
+    cost_models_raw: Record<string, number[]>;
+}
 export interface BackgroundImageDetails {
     image: string;
     creatorDefaults?: ICreatorDefaults;
@@ -52,11 +72,24 @@ export interface ChainProvider {
     getAssetDatum(policyId: string, hex: string): Promise<string | null>;
     getCip25AssetImage(policyId: string, hex: string): Promise<string | null>;
     getRefScriptCbor(tx: string, policyId: string, hex: string): Promise<string>;
+    /** The tx's outputs. Rejects with `status: 404` when the tx is not on chain (not in a block yet). */
     getTxUtxos(tx: string): Promise<ChainProviderUtxo>;
     getAssetUtxo(policyId: string, hex: string): Promise<ChainProviderAsset | null>;
     getAssetsByStakeKey(stakeKey: string): Promise<AccountAsset[]>;
     getDatumFromHash(datumHash: string): Promise<string | null>;
     getBackgroundImageDetails(policyId: string, hex: string): Promise<BackgroundImageDetails>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
+    /** Every unspent output at the address (all pages). An address with no UTxOs has none. */
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    /**
+     * The tx that spent output `txHash#outputIndex`, or null while it is unspent. Rejects with
+     * `status: 404` when that output does not exist (e.g. the tx is not in a block yet).
+     */
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    /**
+     * The asset's `onchain_metadata` as Blockfrost reports it (CIP-68 reference datum converted per
+     * `cip68OnchainMetadata`, else the CIP-25 721 entry), or null when it has none.
+     */
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }

package/chain/index.d.ts

@@ -8,3 +8,4 @@ export * from './config';
 export * from './datum/imageDatum';
 export * from './providers/Koios';
 export * from './providers/Blockfrost';
+export * from './datum/cip68Metadata';

package/chain/index.js

@@ -27,3 +27,4 @@ __exportStar(require("./config"), exports);
 __exportStar(require("./datum/imageDatum"), exports);
 __exportStar(require("./providers/Koios"), exports);
 __exportStar(require("./providers/Blockfrost"), exports);
+__exportStar(require("./datum/cip68Metadata"), exports);

package/chain/providers/Blockfrost.d.ts

@@ -1,5 +1,5 @@
 import { ICreatorDefaults } from '../../handles/interfaces';
-import { AccountAsset, AddressInfo, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
+import { AccountAsset, AddressInfo, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
 import { ChainProviderConfig } from '../providerConfig';
 export interface DrepMetadataValue {
     '@value': string;
@@ -55,5 +55,8 @@ export declare class Blockfrost implements ChainProvider {
     }>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }
 export {};

package/chain/providers/Blockfrost.js

@@ -138,7 +138,60 @@ class Blockfrost {
         };
     }
     async getAddressUTxOs(bech32Address) {
-        return await this.fetchBlockfrost(`/addresses/${bech32Address}/utxos`);
+        // Blockfrost pages at 100: never truncate. An address that never received funds is a 404.
+        const all = [];
+        for (let page = 1;; page++) {
+            let batch;
+            try {
+                batch = await this.fetchBlockfrost(`/addresses/${bech32Address}/utxos?count=100&page=${page}`);
+            }
+            catch (error) {
+                if ((error === null || error === void 0 ? void 0 : error.status) === 404)
+                    return all;
+                throw error;
+            }
+            all.push(...batch);
+            if (batch.length < 100)
+                return all;
+        }
+    }
+    async getProtocolParameters() {
+        var _a;
+        const p = await this.fetchBlockfrost('epochs/latest/parameters');
+        return {
+            epoch: p.epoch,
+            min_fee_a: p.min_fee_a,
+            min_fee_b: p.min_fee_b,
+            max_tx_size: p.max_tx_size,
+            coins_per_utxo_size: String(p.coins_per_utxo_size),
+            key_deposit: String(p.key_deposit),
+            price_mem: p.price_mem,
+            price_step: p.price_step,
+            max_tx_ex_mem: String(p.max_tx_ex_mem),
+            max_tx_ex_steps: String(p.max_tx_ex_steps),
+            min_fee_ref_script_cost_per_byte: (_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : null,
+            cost_models_raw: p.cost_models_raw
+        };
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        var _a;
+        const { outputs } = await this.getTxUtxos(txHash);
+        const output = outputs.find((o) => o.output_index === outputIndex);
+        if (!output)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Blockfrost', `Output ${txHash}#${outputIndex}`);
+        return (_a = output.consumed_by_tx) !== null && _a !== void 0 ? _a : null;
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        var _a;
+        try {
+            const asset = await this.fetchBlockfrost(`/assets/${policyId}${hex}`);
+            return (_a = asset === null || asset === void 0 ? void 0 : asset.onchain_metadata) !== null && _a !== void 0 ? _a : null;
+        }
+        catch (error) {
+            if ((error === null || error === void 0 ? void 0 : error.status) === 404)
+                return null;
+            throw error;
+        }
     }
 }
 exports.Blockfrost = Blockfrost;

package/chain/providers/Koios.d.ts

@@ -1,5 +1,5 @@
 import { ICreatorDefaults } from '../../handles/interfaces';
-import { AccountAsset, AddressInfo, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
+import { AccountAsset, AddressInfo, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
 import { ChainProviderConfig } from '../providerConfig';
 interface KoiosAsset {
     quantity: string;
@@ -17,9 +17,11 @@ interface KoiosTxOutput {
         bytes: string | null;
         value: string | null;
     } | null;
-    payment_addr: {
+    /** tx_info outputs carry `payment_addr`; address_utxos / utxo_info rows carry `address` instead. */
+    payment_addr?: {
         bech32: string;
     };
+    address?: string;
     reference_script: {
         bytes: string | null;
         hash: string | null;
@@ -64,5 +66,8 @@ export declare class Koios implements ChainProvider {
     }>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }
 export {};

package/chain/providers/Koios.js

@@ -4,7 +4,12 @@ exports.Koios = exports.buildKoiosAddressUtxoRequestBody = exports.buildKoiosHea
 const types_1 = require("../../types");
 const fetchProviderJson_1 = require("../transport/fetchProviderJson");
 const imageDatum_1 = require("../datum/imageDatum");
+const cip68Metadata_1 = require("../datum/cip68Metadata");
 const providerConfig_1 = require("../providerConfig");
+/** PostgREST page size Koios serves (its maximum). */
+const KOIOS_PAGE = 1000;
+/** Tx hashes per tx_info request when scanning for an output's consumer. */
+const TX_INFO_BATCH = 50;
 const buildKoiosHeaders = (bearerToken) => ({
     'Content-Type': 'application/json',
     ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {})
@@ -58,7 +63,7 @@ class Koios {
         }, [])) !== null && _a !== void 0 ? _a : []);
     }
     async getAssetUtxo(policyId, hex) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const tx = await this.getLatestTransactionForAsset(policyId, hex);
         if (!tx)
             return null;
@@ -74,9 +79,9 @@ class Koios {
         }));
         amount.push({ unit: 'lovelace', quantity: output.value });
         const chainProviderAsset = {
-            address: output.payment_addr.bech32,
+            address: (_b = output.address) !== null && _b !== void 0 ? _b : output.payment_addr.bech32,
             amount,
-            inline_datum: (_c = (_b = output.inline_datum) === null || _b === void 0 ? void 0 : _b.bytes) !== null && _c !== void 0 ? _c : null,
+            inline_datum: (_d = (_c = output.inline_datum) === null || _c === void 0 ? void 0 : _c.bytes) !== null && _d !== void 0 ? _d : null,
             output_index: output.tx_index,
             tx_hash: firstTransaction.tx_hash,
             data_hash: output.datum_hash
@@ -105,7 +110,7 @@ class Koios {
         return (_a = output === null || output === void 0 ? void 0 : output.reference_script_cbor) !== null && _a !== void 0 ? _a : '';
     }
     async buildChainProviderAsset(output) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const amount = output.asset_list.map((a) => ({
             unit: `${a.policy_id}${a.asset_name}`,
             quantity: a.quantity
@@ -115,20 +120,22 @@ class Koios {
             ? await this.getDatumFromHash(output.datum_hash)
             : (_c = (_b = output.inline_datum) === null || _b === void 0 ? void 0 : _b.bytes) !== null && _c !== void 0 ? _c : null;
         return {
-            address: output.payment_addr.bech32,
+            address: (_d = output.address) !== null && _d !== void 0 ? _d : output.payment_addr.bech32,
             amount,
             inline_datum,
             output_index: output.tx_index,
             tx_hash: output.tx_hash,
             data_hash: output.datum_hash,
-            reference_script_hash: (_e = (_d = output.reference_script) === null || _d === void 0 ? void 0 : _d.hash) !== null && _e !== void 0 ? _e : null,
-            reference_script_cbor: (_g = (_f = output.reference_script) === null || _f === void 0 ? void 0 : _f.bytes) !== null && _g !== void 0 ? _g : null
+            reference_script_hash: (_f = (_e = output.reference_script) === null || _e === void 0 ? void 0 : _e.hash) !== null && _f !== void 0 ? _f : null,
+            reference_script_cbor: (_h = (_g = output.reference_script) === null || _g === void 0 ? void 0 : _g.bytes) !== null && _h !== void 0 ? _h : null
         };
     }
     async getTxUtxos(tx) {
         var _a;
         const res = await this.fetchKoios(`/tx_info`, 'POST', JSON.stringify({ _tx_hashes: [tx], _metadata: true, _assets: true }));
         const [firstTransaction] = res;
+        if (!firstTransaction)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Transaction ${tx}`);
         const outputs = [];
         for (const output of (_a = firstTransaction === null || firstTransaction === void 0 ? void 0 : firstTransaction.outputs) !== null && _a !== void 0 ? _a : []) {
             outputs.push(await this.buildChainProviderAsset(output));
@@ -205,12 +212,74 @@ class Koios {
         };
     }
     async getAddressUTxOs(bech32Address) {
-        const result = await this.fetchKoios(`/address_utxos`, 'POST', JSON.stringify((0, exports.buildKoiosAddressUtxoRequestBody)(bech32Address)));
         const utxos = [];
-        for (const output of result) {
-            utxos.push(await this.buildChainProviderAsset(output));
+        for (let offset = 0;; offset += KOIOS_PAGE) {
+            const page = await this.fetchKoios(`/address_utxos?offset=${offset}&limit=${KOIOS_PAGE}`, 'POST', JSON.stringify((0, exports.buildKoiosAddressUtxoRequestBody)(bech32Address)));
+            for (const output of page) {
+                utxos.push(await this.buildChainProviderAsset(output));
+            }
+            if (page.length < KOIOS_PAGE)
+                return utxos;
+        }
+    }
+    async getProtocolParameters() {
+        var _a;
+        // The tip's epoch, not the newest epoch_params row: rows for the next epoch can appear before it starts.
+        const [tip] = await this.fetchKoios('/tip');
+        const [p] = await this.fetchKoios(`/epoch_params?_epoch_no=${tip.epoch_no}`);
+        if (!p)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Protocol parameters for epoch ${tip.epoch_no}`);
+        return {
+            epoch: p.epoch_no,
+            min_fee_a: p.min_fee_a,
+            min_fee_b: p.min_fee_b,
+            max_tx_size: p.max_tx_size,
+            coins_per_utxo_size: String(p.coins_per_utxo_size),
+            key_deposit: String(p.key_deposit),
+            price_mem: p.price_mem,
+            price_step: p.price_step,
+            max_tx_ex_mem: String(p.max_tx_ex_mem),
+            max_tx_ex_steps: String(p.max_tx_ex_steps),
+            min_fee_ref_script_cost_per_byte: (_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : null,
+            cost_models_raw: p.cost_models
+        };
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        const ref = `${txHash}#${outputIndex}`;
+        const [utxo] = await this.fetchKoios('/utxo_info', 'POST', JSON.stringify({ _utxo_refs: [ref], _extended: false }));
+        if (!utxo)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Output ${ref}`);
+        if (!utxo.is_spent)
+            return null;
+        // Koios has no spent-by index: scan the txs touching the output's address from its block on
+        // (inclusive: a chained spend can land in the same block) for the one that consumes it.
+        for (let offset = 0;; offset += KOIOS_PAGE) {
+            const txs = await this.fetchKoios(`/address_txs?order=block_height.asc&offset=${offset}&limit=${KOIOS_PAGE}`, 'POST', JSON.stringify({ _addresses: [utxo.address], _after_block_height: utxo.block_height }));
+            const candidates = txs.map((t) => t.tx_hash).filter((h) => h !== txHash);
+            for (let i = 0; i < candidates.length; i += TX_INFO_BATCH) {
+                const infos = await this.fetchKoios('/tx_info', 'POST', JSON.stringify({ _tx_hashes: candidates.slice(i, i + TX_INFO_BATCH), _inputs: true, _metadata: false, _assets: false, _withdrawals: false, _certs: false, _scripts: false, _bytecode: false, _governance: false }));
+                const consumer = infos.find((t) => { var _a; return (_a = t.inputs) === null || _a === void 0 ? void 0 : _a.some((input) => input.tx_hash === txHash && input.tx_index === outputIndex); });
+                if (consumer)
+                    return consumer.tx_hash;
+            }
+            if (txs.length < KOIOS_PAGE)
+                break;
+        }
+        throw new Error(`Koios reports ${ref} spent but no tx at ${utxo.address} consumes it`);
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        var _a, _b, _c, _d;
+        // Blockfrost's precedence: a CIP-68 user token's reference datum, else the CIP-25 721 entry.
+        const cip68 = (0, cip68Metadata_1.cip68ReferenceOf)(hex);
+        if (cip68) {
+            const datum = await this.getAssetDatum(policyId, cip68.referenceHex);
+            const metadata = datum ? (0, cip68Metadata_1.cip68OnchainMetadata)(datum, cip68.standard) : null;
+            if (metadata)
+                return metadata;
         }
-        return utxos;
+        const [info] = await this.fetchKoios('/asset_info', 'POST', JSON.stringify({ _asset_list: [[policyId, hex]] }));
+        const byPolicy = (_b = (_a = info === null || info === void 0 ? void 0 : info.minting_tx_metadata) === null || _a === void 0 ? void 0 : _a['721']) === null || _b === void 0 ? void 0 : _b[policyId];
+        return (_d = (_c = byPolicy === null || byPolicy === void 0 ? void 0 : byPolicy[hex]) !== null && _c !== void 0 ? _c : byPolicy === null || byPolicy === void 0 ? void 0 : byPolicy[Buffer.from(hex, 'hex').toString('utf8')]) !== null && _d !== void 0 ? _d : null;
     }
 }
 exports.Koios = Koios;

package/chain/transport/fetchProviderJson.d.ts

@@ -25,6 +25,8 @@ export interface ProviderRequestOptions {
     maxRateLimitWaitMs?: number;
     fetcher?: ProviderFetcher;
 }
+/** A provider's "that does not exist" answer, shaped like a transport 404 (`status: 404`). */
+export declare const providerNotFoundError: (provider: ProviderName, what: string) => Error;
 export declare const isRetriableError: (provider: ProviderName, error: any) => boolean;
 export declare const fetchProviderJson: <T>({ provider, url, method, headers, body, maxRetries, retryBaseDelayMs, maxRps, rateLimitKey, maxRateLimitWaitMs, fetcher }: ProviderRequestOptions) => Promise<T>;
 export {};