@koralabs/kora-labs-common 6.9.4 → 6.11.0

package/aws/jwtSigner.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
 /** True when a local RSA key is configured (i.e. signing/verifying needs no AWS). */
 export declare const isLocalJwtSigner: () => boolean;
 /** Sign `message` with RS256 — local private key if present, else AWS KMS. */

package/aws/kmsEnvironment.d.ts

@@ -1,11 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
 import { KMSClient } from '@aws-sdk/client-kms';
 export type KmsClientLike = Pick<KMSClient, 'send'>;
 /**

package/aws/kmsEnvironment.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadAfterHydratingKmsEnvironment = exports.hydrateKmsEnvironment = exports.decryptKmsCiphertext = exports.isKmsDisabled = void 0;
+exports.isKmsDisabled = void 0;
+exports.decryptKmsCiphertext = decryptKmsCiphertext;
+exports.hydrateKmsEnvironment = hydrateKmsEnvironment;
+exports.loadAfterHydratingKmsEnvironment = loadAfterHydratingKmsEnvironment;
 const client_kms_1 = require("@aws-sdk/client-kms");
 const KMS_ENV_BUNDLE_KEY = 'KMS_ENV_BUNDLE_ENC';
 const KMS_DISABLED_KEY = 'KORA_KMS_DISABLED';
@@ -21,7 +24,6 @@ async function decryptKmsCiphertext(ciphertext, client = new client_kms_1.KMSCli
     }
     return Buffer.from(response.Plaintext).toString('utf8');
 }
-exports.decryptKmsCiphertext = decryptKmsCiphertext;
 async function hydrateKmsEnvironment({ env = process.env, client, keys } = {}) {
     // Self-host: SOPS/age decrypts the env at deploy time, so the values are already
     // plaintext and there is no KMS to call. Skip decryption entirely (don't even
@@ -83,9 +85,7 @@ async function hydrateKmsEnvironment({ env = process.env, client, keys } = {}) {
     }
     return hydratedKeys;
 }
-exports.hydrateKmsEnvironment = hydrateKmsEnvironment;
 async function loadAfterHydratingKmsEnvironment(load, options) {
     await hydrateKmsEnvironment(options);
     return load();
 }
-exports.loadAfterHydratingKmsEnvironment = loadAfterHydratingKmsEnvironment;

package/aws/objectStore.d.ts

@@ -1,11 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
 export interface ObjectStoreConfig {
     region: string;
     endpoint?: string;

package/chain/cache/ShortTermCache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Process-local short-TTL cache with in-flight de-duplication. Concurrent identical requests share
+ * a single upstream fetch, and a successful result is served from memory for `ttlMs`. Failures are
+ * NEVER cached (the fetcher promise only writes to the store on resolve). The clock is injectable so
+ * TTL behavior is unit-testable. Ported from the handle.me BFF into kora-labs-common.
+ */
+export declare class ShortTermCache {
+    private readonly now;
+    private store;
+    private inflight;
+    constructor(now?: () => number);
+    get<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T>;
+    delete(key: string): void;
+    clear(): void;
+}
+/** Shared process-local cache instance for repetitive chain reads. */
+export declare const sharedShortTermCache: ShortTermCache;

package/chain/cache/ShortTermCache.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedShortTermCache = exports.ShortTermCache = void 0;
+/**
+ * Process-local short-TTL cache with in-flight de-duplication. Concurrent identical requests share
+ * a single upstream fetch, and a successful result is served from memory for `ttlMs`. Failures are
+ * NEVER cached (the fetcher promise only writes to the store on resolve). The clock is injectable so
+ * TTL behavior is unit-testable. Ported from the handle.me BFF into kora-labs-common.
+ */
+class ShortTermCache {
+    constructor(now = Date.now) {
+        this.now = now;
+        this.store = new Map();
+        this.inflight = new Map();
+    }
+    async get(key, ttlMs, fetcher) {
+        const hit = this.store.get(key);
+        if (hit && hit.expiresAt > this.now()) {
+            return hit.value;
+        }
+        const pending = this.inflight.get(key);
+        if (pending) {
+            return pending;
+        }
+        const promise = (async () => {
+            const value = await fetcher();
+            this.store.set(key, { value, expiresAt: this.now() + ttlMs });
+            return value;
+        })().finally(() => {
+            this.inflight.delete(key);
+        });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    delete(key) {
+        this.store.delete(key);
+        this.inflight.delete(key);
+    }
+    clear() {
+        this.store.clear();
+        this.inflight.clear();
+    }
+}
+exports.ShortTermCache = ShortTermCache;
+/** Shared process-local cache instance for repetitive chain reads. */
+exports.sharedShortTermCache = new ShortTermCache();

package/chain/config.d.ts

@@ -0,0 +1,9 @@
+import { ChainProvider } from './failover/interfaces';
+import { ChainProviderConfig } from './providerConfig';
+export * from './providerConfig';
+/** Read a ChainProviderConfig from the standard environment variables. */
+export declare const chainConfigFromEnv: (env?: NodeJS.ProcessEnv) => ChainProviderConfig;
+/**
+ * Factory for the default read-failover provider set: Koios + Blockfrost, mutually redundant.
+ */
+export declare const buildChainProviders: (config: ChainProviderConfig) => ChainProvider[];

package/chain/config.js

@@ -0,0 +1,40 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChainProviders = exports.chainConfigFromEnv = void 0;
+const providerConfig_1 = require("./providerConfig");
+const Koios_1 = require("./providers/Koios");
+const Blockfrost_1 = require("./providers/Blockfrost");
+__exportStar(require("./providerConfig"), exports);
+/** Read a ChainProviderConfig from the standard environment variables. */
+const chainConfigFromEnv = (env = process.env) => {
+    var _a, _b, _c, _d;
+    return ({
+        network: (0, providerConfig_1.normalizeNetwork)((_a = env.NETWORK) !== null && _a !== void 0 ? _a : 'mainnet'),
+        koiosBearerToken: ((_b = env.KOIOS_API_BEARER_TOKEN) === null || _b === void 0 ? void 0 : _b.trim()) || undefined,
+        blockfrostApiKey: ((_c = env.BLOCKFROST_API_KEY) === null || _c === void 0 ? void 0 : _c.trim()) || undefined,
+        apiHost: ((_d = env.HANDLE_API_ENDPOINT) === null || _d === void 0 ? void 0 : _d.trim()) || undefined
+    });
+};
+exports.chainConfigFromEnv = chainConfigFromEnv;
+/**
+ * Factory for the default read-failover provider set: Koios + Blockfrost, mutually redundant.
+ */
+const buildChainProviders = (config) => [
+    new Koios_1.Koios(config),
+    new Blockfrost_1.Blockfrost(config)
+];
+exports.buildChainProviders = buildChainProviders;

package/chain/datum/imageDatum.d.ts

@@ -0,0 +1,14 @@
+import { ICreatorDefaults } from '../../handles/interfaces';
+export declare const decodeDatumViaApi: <T>(apiHost: string, datum: string, schema?: Record<string, unknown>, fetcher?: (url: string, init?: any) => Promise<{
+    text: () => Promise<string>;
+}>) => Promise<T>;
+export declare const decode0xHexToUtf8: (v: unknown) => unknown;
+export declare const normalizeCreatorDefaultTextFields: (creatorDefaults: Record<string, unknown>) => void;
+export interface ImageDatumDetails {
+    image: string;
+    creatorDefaults?: ICreatorDefaults;
+    metadata?: Record<string, unknown>;
+}
+export declare const getImageDataFromDatum: (apiHost: string, datum: string, fetcher?: (url: string, init?: any) => Promise<{
+    text: () => Promise<string>;
+}>) => Promise<ImageDatumDetails>;

package/chain/datum/imageDatum.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImageDataFromDatum = exports.normalizeCreatorDefaultTextFields = exports.decode0xHexToUtf8 = exports.decodeDatumViaApi = void 0;
+// Schema-guided datum decoding for background/CIP-68 image details. Ported verbatim (behavior-
+// preserving) from the handle.me BFF: it POSTs the datum CBOR to the Handles API `/datum` decoder
+// with a field schema so specific TEXT fields are UTF-8-decoded. This is handle-property-correctness
+// critical — the schema and the 0x-hex fallback below must not drift.
+const defaultFetch = (url, init) => globalThis.fetch(url, init);
+const decodeDatumViaApi = async (apiHost, datum, schema, fetcher = defaultFetch) => {
+    const response = await fetcher(`${apiHost}/datum?from=plutus_data_cbor&to=json`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ cbor: datum, schema })
+    });
+    const text = await response.text();
+    if (!text.trim()) {
+        // Empty response — return empty object instead of crashing.
+        return {};
+    }
+    return JSON.parse(text);
+};
+exports.decodeDatumViaApi = decodeDatumViaApi;
+// The api /datum decoder only UTF-8-decodes fields the schema can path to. When a background's
+// CIP-68 `extra` is Constr-wrapped (Constr(0,[map]) at [2]), the schema's `[2]` fields don't match
+// and these TEXT fields come back as `0x<hex>`. Colours/arrays are legitimately hex and left alone;
+// only the known free-text fields are normalized back to UTF-8. A value already decoded (no 0x
+// prefix) passes through unchanged.
+const CREATOR_DEFAULT_TEXT_FIELDS = [
+    'font',
+    'qr_dot',
+    'qr_inner_eye',
+    'qr_outer_eye',
+    'text_ribbon_gradient',
+    'qr_image'
+];
+const decode0xHexToUtf8 = (v) => {
+    if (typeof v === 'string' && /^0x[0-9a-fA-F]*$/.test(v) && v.length > 2) {
+        try {
+            return Buffer.from(v.slice(2), 'hex').toString('utf8');
+        }
+        catch (_a) {
+            return v;
+        }
+    }
+    return v;
+};
+exports.decode0xHexToUtf8 = decode0xHexToUtf8;
+const normalizeCreatorDefaultTextFields = (creatorDefaults) => {
+    for (const field of CREATOR_DEFAULT_TEXT_FIELDS) {
+        if (field in creatorDefaults) {
+            creatorDefaults[field] = (0, exports.decode0xHexToUtf8)(creatorDefaults[field]);
+        }
+    }
+};
+exports.normalizeCreatorDefaultTextFields = normalizeCreatorDefaultTextFields;
+const getImageDataFromDatum = async (apiHost, datum, fetcher) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    let decodedDatum;
+    try {
+        decodedDatum = await (0, exports.decodeDatumViaApi)(apiHost, datum, {
+            constructor_0: {
+                '[0]': { name: 'string', image: 'string', category: 'string' },
+                '[2]': {
+                    font: 'string',
+                    text_ribbon_gradient: 'string',
+                    force_creator_settings: 'bool',
+                    qr_inner_eye: 'string',
+                    qr_outer_eye: 'string',
+                    qr_dot: 'string',
+                    qr_image: 'string'
+                }
+            }
+        }, fetcher);
+    }
+    catch (_j) {
+        return { image: '' };
+    }
+    const image = (_b = (_a = decodedDatum === null || decodedDatum === void 0 ? void 0 : decodedDatum.constructor_0) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.image;
+    let data = { image };
+    const creatorDefaults = (_f = (_e = (_d = (_c = decodedDatum === null || decodedDatum === void 0 ? void 0 : decodedDatum.constructor_0) === null || _c === void 0 ? void 0 : _c[2]) === null || _d === void 0 ? void 0 : _d.constructor_0) === null || _e === void 0 ? void 0 : _e[0]) !== null && _f !== void 0 ? _f : (_g = decodedDatum.constructor_0) === null || _g === void 0 ? void 0 : _g[2];
+    if (creatorDefaults) {
+        (0, exports.normalizeCreatorDefaultTextFields)(creatorDefaults);
+        data = { image, creatorDefaults, metadata: (_h = decodedDatum === null || decodedDatum === void 0 ? void 0 : decodedDatum.constructor_0) === null || _h === void 0 ? void 0 : _h[0] };
+    }
+    return data;
+};
+exports.getImageDataFromDatum = getImageDataFromDatum;

package/chain/failover/ChainProviderFailover.d.ts

@@ -0,0 +1,50 @@
+import { AccountAsset, AddressInfo, BackgroundImageDetails, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from './interfaces';
+export interface FailoverOptions {
+    /**
+     * Cooldown (ms) during which a provider that just failed is skipped as the *start* provider,
+     * so a throttled/down provider doesn't add latency to every subsequent call. It is still used
+     * as a fallback if the others also fail. Set 0 to disable (pure random start = legacy behavior).
+     */
+    unhealthyCooldownMs?: number;
+    now?: () => number;
+    /** Injectable RNG in [0,1) for deterministic start selection in tests. Defaults to Math.random. */
+    random?: () => number;
+}
+/**
+ * Health-aware failover across interchangeable ChainProviders. Reads start on a healthy provider
+ * (random among healthy, else random overall) and fall through to the next on error — giving mutual
+ * Koios/Blockfrost redundancy from a single call site. Ported from the handle.me BFF and generalized
+ * (no app-level constants) so every repo shares it via kora-labs-common.
+ */
+export declare class ChainProviderFailover {
+    private providers;
+    private unhealthyUntil;
+    private readonly cooldownMs;
+    private readonly now;
+    private readonly random;
+    constructor(providers: ChainProvider[], options?: FailoverOptions);
+    private isHealthy;
+    private getStartIndex;
+    private getNextProviderIndex;
+    private getResponse;
+    getLatestTransactionForAsset(policyId: string, hex: string): Promise<string | null>;
+    getLatestBlock(): Promise<{
+        height: number;
+        slot: number;
+        time: number;
+    }>;
+    getAssets(policyId: string): Promise<{
+        policyId: string;
+        hex: string;
+    }[]>;
+    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>;
+    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>;
+    getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+}

package/chain/failover/ChainProviderFailover.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainProviderFailover = void 0;
+/**
+ * Health-aware failover across interchangeable ChainProviders. Reads start on a healthy provider
+ * (random among healthy, else random overall) and fall through to the next on error — giving mutual
+ * Koios/Blockfrost redundancy from a single call site. Ported from the handle.me BFF and generalized
+ * (no app-level constants) so every repo shares it via kora-labs-common.
+ */
+class ChainProviderFailover {
+    constructor(providers, options = {}) {
+        var _a, _b, _c;
+        this.providers = [];
+        this.unhealthyUntil = [];
+        this.providers = providers;
+        this.unhealthyUntil = providers.map(() => 0);
+        this.cooldownMs = (_a = options.unhealthyCooldownMs) !== null && _a !== void 0 ? _a : 30000;
+        this.now = (_b = options.now) !== null && _b !== void 0 ? _b : Date.now;
+        this.random = (_c = options.random) !== null && _c !== void 0 ? _c : Math.random;
+    }
+    isHealthy(index) {
+        return this.unhealthyUntil[index] <= this.now();
+    }
+    getStartIndex() {
+        const healthy = this.providers.map((_, i) => i).filter((i) => this.isHealthy(i));
+        const pool = healthy.length > 0 ? healthy : this.providers.map((_, i) => i);
+        return pool[Math.floor(this.random() * pool.length)];
+    }
+    getNextProviderIndex(currentIndex) {
+        return (currentIndex + 1) % this.providers.length;
+    }
+    async getResponse(funcName, args, currentIndex, runNum) {
+        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) => {
+            // 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)
+                this.unhealthyUntil[index] = this.now() + this.cooldownMs;
+            if (num === this.providers.length - 1)
+                throw error;
+            return this.getResponse(funcName, args, this.getNextProviderIndex(index), num + 1);
+        });
+    }
+    async getLatestTransactionForAsset(policyId, hex) {
+        return this.getResponse('getLatestTransactionForAsset', [policyId, hex]);
+    }
+    async getLatestBlock() {
+        return this.getResponse('getLatestBlock', []);
+    }
+    async getAssets(policyId) {
+        return this.getResponse('getAssets', [policyId]);
+    }
+    async getAssetDatum(policyId, hex) {
+        return this.getResponse('getAssetDatum', [policyId, hex]);
+    }
+    async getCip25AssetImage(policyId, hex) {
+        return this.getResponse('getCip25AssetImage', [policyId, hex]);
+    }
+    async getRefScriptCbor(tx, policyId, hex) {
+        return this.getResponse('getRefScriptCbor', [tx, policyId, hex]);
+    }
+    async getTxUtxos(tx) {
+        return this.getResponse('getTxUtxos', [tx]);
+    }
+    async getAssetUtxo(policyId, hex) {
+        // Asset resolution is correctness-critical (backs handle-resolution chain fallback): a
+        // 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);
+    }
+    async getAssetsByStakeKey(stakeKey) {
+        return this.getResponse('getAssetsByStakeKey', [stakeKey]);
+    }
+    async getDatumFromHash(datumHash) {
+        return this.getResponse('getDatumFromHash', [datumHash]);
+    }
+    async getBackgroundImageDetails(policyId, hex) {
+        return this.getResponse('getBackgroundImageDetails', [policyId, hex]);
+    }
+    async getAddressInfo(bech32Address) {
+        return this.getResponse('getAddressInfo', [bech32Address]);
+    }
+    async getAddressUTxOs(bech32Address) {
+        return this.getResponse('getAddressUTxOs', [bech32Address]);
+    }
+}
+exports.ChainProviderFailover = ChainProviderFailover;

package/chain/failover/interfaces.d.ts

@@ -0,0 +1,62 @@
+import { ICreatorDefaults } from '../../handles/interfaces';
+export interface ChainProviderAsset {
+    address: string;
+    amount: {
+        unit: string;
+        quantity: string;
+    }[];
+    inline_datum: string | null;
+    output_index: number;
+    tx_hash: string;
+    data_hash: string | null;
+    reference_script_hash?: string | null;
+    reference_script_cbor?: string | null;
+}
+export interface ChainProviderUtxo {
+    outputs: ChainProviderAsset[];
+}
+export interface AccountAsset {
+    asset: string;
+    amount: string;
+}
+export interface AddressInfo {
+    address: string;
+    amount: {
+        unit: string;
+        quantity: string;
+    }[];
+    stake_address?: string | null;
+    script: boolean;
+}
+export interface BackgroundImageDetails {
+    image: string;
+    creatorDefaults?: ICreatorDefaults;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The unified read contract every chain provider (Koios, Blockfrost, …) implements. The failover
+ * orchestrator only depends on this interface, so providers are hot-swappable and mutually redundant.
+ */
+export interface ChainProvider {
+    name: string;
+    getLatestTransactionForAsset(policyId: string, hex: string): Promise<string | null>;
+    getLatestBlock(): Promise<{
+        height: number;
+        slot: number;
+        time: number;
+    }>;
+    getAssets(policyId: string): Promise<{
+        policyId: string;
+        hex: string;
+    }[]>;
+    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>;
+    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>;
+    getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+}

package/chain/failover/interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/chain/index.d.ts

@@ -0,0 +1,9 @@
+export * from './transport/fetchProviderJson';
+export * from './failover/interfaces';
+export * from './failover/ChainProviderFailover';
+export * from './cache/ShortTermCache';
+export * from './providerConfig';
+export * from './config';
+export * from './datum/imageDatum';
+export * from './providers/Koios';
+export * from './providers/Blockfrost';

package/chain/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath-only module: `@koralabs/kora-labs-common/chain`.
+// NOT re-exported from the root index — this is a server-side chain-access layer and pulls Node-only
+// deps. Keeping it off the root barrel preserves the isomorphic root (same rule the `aws` module follows).
+__exportStar(require("./transport/fetchProviderJson"), exports);
+__exportStar(require("./failover/interfaces"), exports);
+__exportStar(require("./failover/ChainProviderFailover"), exports);
+__exportStar(require("./cache/ShortTermCache"), exports);
+__exportStar(require("./providerConfig"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./datum/imageDatum"), exports);
+__exportStar(require("./providers/Koios"), exports);
+__exportStar(require("./providers/Blockfrost"), exports);

package/chain/providerConfig.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Configuration for the concrete chain providers. Injected explicitly (no reading of app-level
+ * constants) so every consumer wires its own env once and the module stays app-agnostic.
+ */
+export interface ChainProviderConfig {
+    /** 'mainnet' | 'preview' | 'preprod' — selects Koios/Blockfrost hosts. */
+    network: string;
+    /** Koios bearer token (optional; anonymous tier works without it). */
+    koiosBearerToken?: string;
+    /** Blockfrost project id for the target network. */
+    blockfrostApiKey?: string;
+    /**
+     * Base URL of the Handles API used for schema-guided datum decoding (POST /datum). Defaults to
+     * the public api.handle.me host for the network. Preserves the exact datum-decode behavior the
+     * BFF relied on (schema-pathed UTF-8 field decoding), which is handle-property-correctness
+     * critical — do NOT swap it for a local CBOR decode without matching that behavior.
+     */
+    apiHost?: string;
+}
+export declare const normalizeNetwork: (network: string) => string;
+/** Public api.handle.me host for a network (mainnet has no subdomain prefix). */
+export declare const defaultApiHost: (network: string) => string;

package/chain/providerConfig.js

@@ -0,0 +1,13 @@
+"use strict";
+// Leaf config module (no imports from providers) so the concrete providers and the factory can both
+// depend on it without a cycle.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultApiHost = exports.normalizeNetwork = void 0;
+const normalizeNetwork = (network) => (network || 'mainnet').toLowerCase();
+exports.normalizeNetwork = normalizeNetwork;
+/** Public api.handle.me host for a network (mainnet has no subdomain prefix). */
+const defaultApiHost = (network) => {
+    const net = (0, exports.normalizeNetwork)(network);
+    return net === 'mainnet' ? 'https://api.handle.me' : `https://${net}.api.handle.me`;
+};
+exports.defaultApiHost = defaultApiHost;

package/chain/providers/Blockfrost.d.ts

@@ -0,0 +1,59 @@
+import { ICreatorDefaults } from '../../handles/interfaces';
+import { AccountAsset, AddressInfo, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
+import { ChainProviderConfig } from '../providerConfig';
+export interface DrepMetadataValue {
+    '@value': string;
+}
+export interface DrepReference {
+    '@type': string;
+    label: string | DrepMetadataValue;
+    uri: string | DrepMetadataValue;
+}
+interface DrepMetadata {
+    drep_id: string;
+    json_metadata: {
+        body: {
+            paymentAddress: string | DrepMetadataValue;
+            givenName: string | DrepMetadataValue;
+            image: {
+                contentUrl: string | DrepMetadataValue;
+            };
+            objectives: string | DrepMetadataValue;
+            motivations: string | DrepMetadataValue;
+            qualifications: string | DrepMetadataValue;
+            references: DrepReference[];
+        };
+    };
+}
+export declare class Blockfrost implements ChainProvider {
+    private readonly config;
+    name: string;
+    constructor(config: ChainProviderConfig);
+    private fetchBlockfrost;
+    getDrepMetadata(drepId: string): Promise<DrepMetadata>;
+    getLatestBlock(): Promise<{
+        height: number;
+        slot: number;
+        time: number;
+    }>;
+    getLatestTransactionForAsset(policyId: string, hex: string): Promise<string | null>;
+    getAssets(policyId: string): Promise<{
+        policyId: string;
+        hex: string;
+    }[]>;
+    getAssetUtxo(policyId: string, hex: string): Promise<ChainProviderAsset | null>;
+    getDatumFromHash(datumHash: string): Promise<string | null>;
+    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>;
+    getTxUtxos(tx: string): Promise<ChainProviderUtxo>;
+    getAssetsByStakeKey(stakeKey: string): Promise<AccountAsset[]>;
+    getBackgroundImageDetails(policyId: string, hex: string): Promise<{
+        image: string;
+        creatorDefaults?: ICreatorDefaults;
+        metadata?: Record<string, unknown>;
+    }>;
+    getAddressInfo(bech32Address: string): Promise<AddressInfo>;
+    getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+}
+export {};