@koralabs/kora-labs-common 6.15.3 → 6.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.15.3",
+    "version": "6.17.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",

package/testing/blockfrost.d.ts

@@ -0,0 +1,12 @@
+export type LiveNetwork = 'preview' | 'preprod' | 'mainnet';
+export interface BlockfrostAccess {
+    network: LiveNetwork;
+    blockfrostApiKey: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+export declare const blockfrostBaseUrl: (network: LiveNetwork) => string;
+/** GET `path`; null when Blockfrost answers 404 (never used / not on chain yet). */
+export declare const blockfrostGet: <T>(access: BlockfrostAccess, path: string) => Promise<T | null>;
+/** POST a signed tx to `/tx/submit`; resolves to the tx hash, or throws with the node's reason. */
+export declare const blockfrostSubmit: (access: BlockfrostAccess, signedTxCbor: string) => Promise<string>;

package/testing/blockfrost.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockfrostSubmit = exports.blockfrostGet = exports.blockfrostBaseUrl = void 0;
+/**
+ * Blockfrost access for the live-suite harness. Every call goes through the shared rate-limited
+ * transport (`chain/transport/fetchProviderJson`): a stated wait (Retry-After and friends) is
+ * remembered process-wide and never undercut, and a wait too long to sit out surfaces as
+ * `RateLimitedError` instead of a retry.
+ */
+const fetchProviderJson_1 = require("../chain/transport/fetchProviderJson");
+const blockfrostBaseUrl = (network) => `https://cardano-${network}.blockfrost.io/api/v0`;
+exports.blockfrostBaseUrl = blockfrostBaseUrl;
+const request = (access, path, init = {}) => {
+    var _a;
+    return (0, fetchProviderJson_1.fetchProviderJson)({
+        provider: 'Blockfrost',
+        url: `${(0, exports.blockfrostBaseUrl)(access.network)}${path}`,
+        method: (_a = init.method) !== null && _a !== void 0 ? _a : 'GET',
+        headers: { project_id: access.blockfrostApiKey, ...(init.contentType ? { 'Content-Type': init.contentType } : {}) },
+        body: init.body,
+        fetcher: access.fetchFn
+    });
+};
+/** GET `path`; null when Blockfrost answers 404 (never used / not on chain yet). */
+const blockfrostGet = async (access, path) => {
+    try {
+        return await request(access, path);
+    }
+    catch (error) {
+        if (error.status === 404)
+            return null;
+        throw error;
+    }
+};
+exports.blockfrostGet = blockfrostGet;
+/** POST a signed tx to `/tx/submit`; resolves to the tx hash, or throws with the node's reason. */
+const blockfrostSubmit = async (access, signedTxCbor) => {
+    var _a, _b, _c;
+    try {
+        return await request(access, '/tx/submit', { method: 'POST', body: Buffer.from(signedTxCbor, 'hex'), contentType: 'application/cbor' });
+    }
+    catch (error) {
+        const e = error;
+        if (e.status === undefined)
+            throw error;
+        throw new Error(`Submit failed: ${e.status} ${(_c = (_b = (_a = e.blockfrostResponse) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : e.responseText) !== null && _c !== void 0 ? _c : ''}`.trim(), { cause: error });
+    }
+};
+exports.blockfrostSubmit = blockfrostSubmit;

package/testing/index.d.ts

@@ -1,3 +1,4 @@
+export * from './blockfrost';
 export * from './liveWallet';
 export * from './installWallet';
 export * from './readOnlyGuard';

package/testing/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // Subpath module: `@koralabs/kora-labs-common/testing`. Node-only harness for live CIP-30 browser
 // journey suites. NOT re-exported from the root index. Requires the optional peer dependencies
 // @cardano-sdk/core, @cardano-sdk/crypto, bip39 (and @emurgo/cardano-message-signing-nodejs for signData).
+__exportStar(require("./blockfrost"), exports);
 __exportStar(require("./liveWallet"), exports);
 __exportStar(require("./installWallet"), exports);
 __exportStar(require("./readOnlyGuard"), exports);

package/testing/liveWallet.d.ts

@@ -1,4 +1,4 @@
-export type LiveNetwork = 'preview' | 'preprod' | 'mainnet';
+import { LiveNetwork } from './blockfrost';
 export interface LiveWalletConfig {
     mnemonic: string;
     network: LiveNetwork;
@@ -10,6 +10,17 @@ export interface LiveWalletConfig {
     /** Injectable for tests. Defaults to global fetch. */
     fetchFn?: typeof fetch;
 }
+/** One tx this wallet submitted, with the chaining facts a suite asserts on. */
+export interface LiveSubmission {
+    txHash: string;
+    /** Local clock (ms) when the submission was accepted. */
+    submittedAt: number;
+    /**
+     * Inputs (`txHash#index`) that were outputs of this wallet's OWN earlier submissions that were not
+     * in a block yet when this tx was submitted — i.e. the tx is chained on unconfirmed change.
+     */
+    chainedInputs: string[];
+}
 export interface LiveWallet {
     address: string;
     addressHex: string;
@@ -21,7 +32,10 @@ export interface LiveWallet {
     dRepId: string;
     call: (method: string, params?: unknown) => Promise<unknown>;
     submittedTxHashes: string[];
+    /** Every accepted submission, in order (`submittedTxHashes` is the hash-only view). */
+    submissions: LiveSubmission[];
+    /** Hashes of submitted txs this wallet has not yet seen in a block. */
+    pendingTxHashes: () => string[];
     countUtxos: () => Promise<number>;
 }
-export declare const blockfrostBaseUrl: (network: LiveNetwork) => string;
 export declare const createLiveWallet: (config: LiveWalletConfig) => Promise<LiveWallet>;

package/testing/liveWallet.js

@@ -33,13 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLiveWallet = exports.blockfrostBaseUrl = void 0;
+exports.createLiveWallet = void 0;
 /**
  * Live CIP-30 wallet emulator for browser journey suites (Playwright).
  *
  * Real keys derived from a mnemonic (CIP-1852), real UTxOs from Blockfrost, real signatures, real
  * submission. It behaves like a real CIP-30 wallet on purpose:
  *   - getUtxos returns the FULL paginated UTxO set (no hidden/"parked" collateral),
+ *   - it CHAINS like Eternl/Lace: once it has submitted a tx, getUtxos (and getBalance, and the
+ *     signing-key choice) return that tx's outputs to this wallet and drop the inputs it spent, until
+ *     the tx is in a block — then chain truth takes over. A dapp therefore receives UTxOs that exist
+ *     on no provider yet, exactly as real users' wallets hand them over (HAL minting depends on it),
  *   - getCollateral returns null (the common real-wallet case — the app must resolve collateral),
  *   - signTx returns a witness set holding ONLY this wallet's vkey witnesses (the app merges it),
  *   - signTx refuses non-canonical tx structure (hardware wallets / Eternl do).
@@ -48,6 +52,7 @@ exports.createLiveWallet = exports.blockfrostBaseUrl = void 0;
 const blakejs_1 = require("blakejs");
 const bech32_1 = require("bech32");
 const tx_1 = require("../tx");
+const blockfrost_1 = require("./blockfrost");
 const HARDENED = 0x80000000;
 let sdkPromise = null;
 // @cardano-sdk/crypto ships its own nested libsodium-wrappers-sumo; it must be `ready` before any
@@ -67,15 +72,12 @@ const loadSdk = () => {
     })());
     return sdkPromise;
 };
-const blockfrostBaseUrl = (network) => `https://cardano-${network}.blockfrost.io/api/v0`;
-exports.blockfrostBaseUrl = blockfrostBaseUrl;
 const createLiveWallet = async (config) => {
-    var _a, _b;
+    var _a;
     const { Cardano, Serialization, Crypto, bip39 } = await loadSdk();
-    const doFetch = (_a = config.fetchFn) !== null && _a !== void 0 ? _a : fetch;
+    const access = { network: config.network, blockfrostApiKey: config.blockfrostApiKey, fetchFn: config.fetchFn };
     const networkId = config.network === 'mainnet' ? 1 : 0;
-    const base = (0, exports.blockfrostBaseUrl)(config.network);
-    const account = (_b = config.accountIndex) !== null && _b !== void 0 ? _b : 0;
+    const account = (_a = config.accountIndex) !== null && _a !== void 0 ? _a : 0;
     const root = Crypto.Bip32PrivateKey.fromBip39Entropy(Buffer.from(bip39.mnemonicToEntropy(config.mnemonic), 'hex'), '');
     const accountKey = root.derive([1852 + HARDENED, 1815 + HARDENED, account + HARDENED]);
     const paymentKey = accountKey.derive([0, 0]).toRawKey();
@@ -96,25 +98,17 @@ const createLiveWallet = async (config) => {
     const dRepPubKeyHex = stakeKey.toPublic().hex();
     const dRepKeyHash = (0, blakejs_1.blake2b)(Buffer.from(dRepPubKeyHex, 'hex'), undefined, 28);
     const dRepId = bech32_1.bech32.encode('drep', bech32_1.bech32.toWords(Uint8Array.from([0x22, ...dRepKeyHash])), 128);
+    const ownAddresses = new Set([address, enterpriseStakeAddress]);
     const submittedTxHashes = [];
-    const fetchBlockfrost = async (path) => {
-        const res = await doFetch(`${base}${path}`, { headers: { project_id: config.blockfrostApiKey } });
-        if (!res.ok)
-            throw new Error(`Blockfrost ${path}: ${res.status} ${(await res.text()).slice(0, 200)}`);
-        return res;
-    };
+    const submissions = [];
+    const pending = new Map();
     const fetchAddressUtxos = async (addr) => {
         const all = [];
         for (let page = 1;; page++) {
-            const res = await doFetch(`${base}/addresses/${addr}/utxos?count=100&page=${page}`, {
-                headers: { project_id: config.blockfrostApiKey }
-            });
-            // 404 = the address has never been used — an empty set, not an error.
-            if (res.status === 404)
+            // null (404) = the address has never been used — an empty set, not an error.
+            const batch = await (0, blockfrost_1.blockfrostGet)(access, `/addresses/${addr}/utxos?count=100&page=${page}`);
+            if (!batch)
                 break;
-            if (!res.ok)
-                throw new Error(`Blockfrost /addresses/${addr}/utxos: ${res.status} ${(await res.text()).slice(0, 200)}`);
-            const batch = (await res.json());
             for (const u of batch)
                 u._sourceAddr = addr;
             all.push(...batch);
@@ -138,30 +132,50 @@ const createLiveWallet = async (config) => {
         };
         return new Serialization.TransactionUnspentOutput(Serialization.TransactionInput.fromCore({ txId: u.tx_hash, index: u.output_index }), Serialization.TransactionOutput.fromCore(output)).toCbor();
     };
-    const getUtxos = async () => {
-        const utxos = [...(await fetchAddressUtxos(address)), ...(await fetchAddressUtxos(enterpriseStakeAddress))];
-        return utxos.map(utxoToCborHex);
+    /** A pending tx that is now in a block leaves the overlay: chain truth takes over. */
+    const settlePending = async () => {
+        for (const txHash of [...pending.keys()]) {
+            if (await (0, blockfrost_1.blockfrostGet)(access, `/txs/${txHash}`))
+                pending.delete(txHash);
+        }
+    };
+    /** The wallet's own view: chain UTxOs, minus what its pending txs spent, plus their unspent change. */
+    const ownUtxos = async () => {
+        var _a, _b, _c;
+        await settlePending();
+        const chainUtxos = [...(await fetchAddressUtxos(address)), ...(await fetchAddressUtxos(enterpriseStakeAddress))];
+        const spent = new Set([...pending.values()].flatMap((p) => [...p.spends]));
+        const view = new Map();
+        for (const u of chainUtxos) {
+            const ref = `${u.tx_hash}#${u.output_index}`;
+            if (spent.has(ref))
+                continue;
+            view.set(ref, { cbor: utxoToCborHex(u), address: (_a = u._sourceAddr) !== null && _a !== void 0 ? _a : address, lovelace: BigInt((_c = (_b = u.amount.find((a) => a.unit === 'lovelace')) === null || _b === void 0 ? void 0 : _b.quantity) !== null && _c !== void 0 ? _c : '0') });
+        }
+        for (const p of pending.values()) {
+            for (const [ref, out] of p.outputs)
+                if (!spent.has(ref))
+                    view.set(ref, out);
+        }
+        return view;
     };
+    const getUtxos = async () => [...(await ownUtxos()).values()].map((u) => u.cbor);
     const getBalance = async () => {
-        const utxos = await fetchAddressUtxos(address);
-        const coins = utxos.reduce((sum, u) => { var _a, _b; return sum + BigInt((_b = (_a = u.amount.find((a) => a.unit === 'lovelace')) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0'); }, BigInt(0));
+        const coins = [...(await ownUtxos()).values()].filter((u) => u.address === address).reduce((sum, u) => sum + u.lovelace, BigInt(0));
         return Serialization.Value.fromCore({ coins }).toCbor();
     };
-    // The stake key must sign when it is a required signer, or when the tx spends/collateralizes a
-    // UTxO whose PAYMENT credential is the stake key (EnterpriseAddress(stakeCredential)).
+    // The stake key must sign when it is a required signer, or when the tx spends/collateralizes one of
+    // this wallet's UTxOs whose PAYMENT credential is the stake key (EnterpriseAddress(stakeCredential)).
+    // Resolved from the wallet's own view, like a real wallet: chained inputs are on no provider yet.
     const needsStakeKeySignature = async (body) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         if (((_a = body.requiredExtraSignatures) !== null && _a !== void 0 ? _a : []).some((s) => s === stakeKeyHash))
             return true;
         const inputs = [...((_b = body.inputs) !== null && _b !== void 0 ? _b : []), ...((_c = body.collaterals) !== null && _c !== void 0 ? _c : [])];
-        for (const input of inputs) {
-            const res = await fetchBlockfrost(`/txs/${input.txId}/utxos`);
-            const json = (await res.json());
-            const out = (_d = json.outputs) === null || _d === void 0 ? void 0 : _d.find((o, i) => { var _a; return ((_a = o.output_index) !== null && _a !== void 0 ? _a : i) === input.index; });
-            if ((out === null || out === void 0 ? void 0 : out.address) === enterpriseStakeAddress)
-                return true;
-        }
-        return false;
+        if (inputs.length === 0)
+            return false;
+        const view = await ownUtxos();
+        return inputs.some((input) => { var _a; return ((_a = view.get(`${input.txId}#${input.index}`)) === null || _a === void 0 ? void 0 : _a.address) === enterpriseStakeAddress; });
     };
     const signTx = async (txCborHex) => {
         (0, tx_1.assertCanonicalCbor)(txCborHex, 'signTx');
@@ -181,6 +195,23 @@ const createLiveWallet = async (config) => {
             out.push(await signTx(typeof entry === 'string' ? entry : ((_a = entry.cbor) !== null && _a !== void 0 ? _a : entry.tx)));
         return out;
     };
+    /** Record an accepted submission: its spent inputs leave the view, its own outputs join it. */
+    const trackSubmitted = (txHash, signedTxCbor) => {
+        const body = Serialization.Transaction.fromCbor(signedTxCbor).body();
+        const spends = new Set(body.inputs().values().map((i) => `${i.transactionId()}#${Number(i.index())}`));
+        const chainedInputs = [...spends].filter((ref) => pending.has(ref.split('#')[0]));
+        const outputs = new Map();
+        body.outputs().forEach((output, index) => {
+            const outAddress = output.address().toBech32();
+            if (!ownAddresses.has(outAddress))
+                return;
+            const cbor = new Serialization.TransactionUnspentOutput(Serialization.TransactionInput.fromCore({ txId: txHash, index }), output).toCbor();
+            outputs.set(`${txHash}#${index}`, { cbor, address: outAddress, lovelace: output.amount().coin() });
+        });
+        pending.set(txHash, { spends, outputs });
+        submittedTxHashes.push(txHash);
+        submissions.push({ txHash, submittedAt: Date.now(), chainedInputs });
+    };
     const submitTx = async (signedTxCbor) => {
         if (config.submitDumpDir) {
             const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
@@ -188,29 +219,14 @@ const createLiveWallet = async (config) => {
             fs.mkdirSync(config.submitDumpDir, { recursive: true });
             fs.writeFileSync(path.join(config.submitDumpDir, `submit-${Date.now()}.cbor.hex`), signedTxCbor);
         }
-        // Retry only transient failures (429/5xx). Any other 4xx is a real ledger rejection and
-        // surfaces immediately with Blockfrost's full reason.
-        const backoffsMs = [0, 1000, 4000, 10000];
-        let lastError = '';
-        for (const wait of backoffsMs) {
-            if (wait)
-                await new Promise((r) => setTimeout(r, wait));
-            const res = await doFetch(`${base}/tx/submit`, {
-                method: 'POST',
-                headers: { project_id: config.blockfrostApiKey, 'Content-Type': 'application/cbor' },
-                body: Buffer.from(signedTxCbor, 'hex')
-            });
-            const text = await res.text();
-            if (res.ok) {
-                const hash = text.replace(/"/g, '');
-                submittedTxHashes.push(hash);
-                return hash;
-            }
-            lastError = `${res.status} ${text.slice(0, 4000)}`;
-            if (!(res.status === 429 || res.status >= 500))
-                break;
-        }
-        throw new Error(`Submit failed: ${lastError}`);
+        // Transient failures (5xx) are retried by the transport; rate limits wait exactly the stated
+        // time; any other 4xx is a real ledger rejection and surfaces with Blockfrost's reason.
+        const hash = await (0, blockfrost_1.blockfrostSubmit)(access, signedTxCbor);
+        const expected = (0, tx_1.txHashFromCbor)(signedTxCbor);
+        if (hash !== expected)
+            throw new Error(`Submit returned ${hash} for tx ${expected}`);
+        trackSubmitted(hash, signedTxCbor);
+        return hash;
     };
     // CIP-8 COSE_Sign1 over the payload with the payment key (CIP-30 signData).
     const signData = async (addrHex, payloadHex) => {
@@ -279,7 +295,9 @@ const createLiveWallet = async (config) => {
         dRepId,
         call,
         submittedTxHashes,
-        countUtxos: async () => (await fetchAddressUtxos(address)).length
+        submissions,
+        pendingTxHashes: () => [...pending.keys()],
+        countUtxos: async () => [...(await ownUtxos()).values()].filter((u) => u.address === address).length
     };
 };
 exports.createLiveWallet = createLiveWallet;

package/testing/onChain.d.ts

@@ -1,14 +1,10 @@
-import { LiveNetwork } from './liveWallet';
+import { BlockfrostAccess } from './blockfrost';
 export declare const LBL_222 = "000de140";
 export declare const LBL_100 = "000643b0";
 export declare const LBL_000 = "00000000";
 export declare const LBL_444 = "001bc280";
 export declare const hexOf: (s: string) => string;
-export interface ChainConfig {
-    network: LiveNetwork;
-    blockfrostApiKey: string;
-    fetchFn?: typeof fetch;
-}
+export type ChainConfig = BlockfrostAccess;
 export interface TxUtxoOutput {
     address: string;
     amount: {

package/testing/onChain.js

@@ -6,22 +6,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cip68Field = exports.fetchCip68ExtraFromTx = exports.fetchOutputDatumCbor = exports.assertAdaTransfer = exports.assertAssetBurned = exports.assertCip68Label = exports.waitForOutputConsumed = exports.waitForTxConfirmation = exports.lovelaceOf = exports.fetchTxUtxos = exports.hexOf = exports.LBL_444 = exports.LBL_000 = exports.LBL_100 = exports.LBL_222 = void 0;
 /**
  * On-chain EFFECT assertions for live journey suites. Chain truth via Blockfrost — never the
- * indexer or the UI. Each assertion throws on mismatch so the calling scope fails.
+ * indexer or the UI. Each assertion throws on mismatch so the calling scope fails. Blockfrost is
+ * reached through the shared rate-limited transport (./blockfrost).
  */
 const cbor_1 = __importDefault(require("cbor"));
-const liveWallet_1 = require("./liveWallet");
+const rateLimit_1 = require("../chain/transport/rateLimit");
+const blockfrost_1 = require("./blockfrost");
 exports.LBL_222 = '000de140'; // CIP-68 user/owner NFT
 exports.LBL_100 = '000643b0'; // CIP-68 reference token
 exports.LBL_000 = '00000000'; // virtual subhandle token
 exports.LBL_444 = '001bc280'; // CIP-68 RFT
 const hexOf = (s) => Buffer.from(s, 'utf8').toString('hex');
 exports.hexOf = hexOf;
-const get = async (chain, path) => { var _a; return ((_a = chain.fetchFn) !== null && _a !== void 0 ? _a : fetch)(`${(0, liveWallet_1.blockfrostBaseUrl)(chain.network)}${path}`, { headers: { project_id: chain.blockfrostApiKey } }); };
 const getJson = async (chain, path) => {
-    const res = await get(chain, path);
-    if (!res.ok)
-        throw new Error(`onChain: GET ${path} failed (${res.status})`);
-    return (await res.json());
+    const found = await (0, blockfrost_1.blockfrostGet)(chain, path);
+    if (found === null)
+        throw new Error(`onChain: GET ${path} failed (404)`);
+    return found;
 };
 const fetchTxUtxos = (chain, txHash) => getJson(chain, `/txs/${txHash}/utxos`);
 exports.fetchTxUtxos = fetchTxUtxos;
@@ -31,11 +32,14 @@ exports.lovelaceOf = lovelaceOf;
 const waitForTxConfirmation = async (chain, txHash, timeoutMs = 180000, pollMs = 5000) => {
     const start = Date.now();
     for (;;) {
-        const res = await get(chain, `/txs/${txHash}`).catch(() => null);
-        if (res === null || res === void 0 ? void 0 : res.ok) {
-            const data = (await res.json());
+        // A transient provider failure is another poll; a rate limit too long to sit out is returned.
+        const data = await (0, blockfrost_1.blockfrostGet)(chain, `/txs/${txHash}`).catch((error) => {
+            if (error instanceof rateLimit_1.RateLimitedError)
+                throw error;
+            return null;
+        });
+        if (data)
             return { confirmed: true, block: data.block, validContract: data.valid_contract };
-        }
         if (Date.now() - start >= timeoutMs)
             return { confirmed: false };
         await new Promise((r) => setTimeout(r, pollMs));
@@ -62,31 +66,27 @@ exports.waitForOutputConsumed = waitForOutputConsumed;
 const assertCip68Label = async (chain, policyId, name, opts) => {
     var _a, _b;
     const nameHex = (0, exports.hexOf)(name);
-    const present = await get(chain, `/assets/${policyId}${opts.hasLabel}${nameHex}`);
-    if (!present.ok)
-        throw new Error(`onChain: expected asset ${opts.hasLabel}+${name} under ${policyId} (${present.status})`);
-    const quantity = BigInt((_a = (await present.json()).quantity) !== null && _a !== void 0 ? _a : '0');
+    const present = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${policyId}${opts.hasLabel}${nameHex}`);
+    if (!present)
+        throw new Error(`onChain: expected asset ${opts.hasLabel}+${name} under ${policyId} (not found)`);
+    const quantity = BigInt((_a = present.quantity) !== null && _a !== void 0 ? _a : '0');
     if (quantity <= BigInt(0))
         throw new Error(`onChain: asset ${opts.hasLabel}+${name} has zero quantity`);
     if (opts.notLabel) {
-        const forbidden = await get(chain, `/assets/${policyId}${opts.notLabel}${nameHex}`);
-        if (forbidden.ok) {
-            const fq = BigInt((_b = (await forbidden.json()).quantity) !== null && _b !== void 0 ? _b : '0');
-            if (fq > BigInt(0))
-                throw new Error(`onChain: asset ${opts.notLabel}+${name} must NOT exist (quantity ${fq})`);
-        }
+        const forbidden = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${policyId}${opts.notLabel}${nameHex}`);
+        const fq = BigInt((_b = forbidden === null || forbidden === void 0 ? void 0 : forbidden.quantity) !== null && _b !== void 0 ? _b : '0');
+        if (fq > BigInt(0))
+            throw new Error(`onChain: asset ${opts.notLabel}+${name} must NOT exist (quantity ${fq})`);
     }
 };
 exports.assertCip68Label = assertCip68Label;
 /** Assert an asset's total on-chain quantity is 0 (burned). */
 const assertAssetBurned = async (chain, assetUnit) => {
     var _a;
-    const res = await get(chain, `/assets/${assetUnit}`);
-    if (res.status === 404)
+    const asset = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${assetUnit}`);
+    if (!asset)
         return;
-    if (!res.ok)
-        throw new Error(`onChain: asset lookup failed (${res.status})`);
-    const quantity = (_a = (await res.json()).quantity) !== null && _a !== void 0 ? _a : '0';
+    const quantity = (_a = asset.quantity) !== null && _a !== void 0 ? _a : '0';
     if (BigInt(quantity) !== BigInt(0))
         throw new Error(`onChain: expected ${assetUnit} burned, quantity is ${quantity}`);
 };

package/wallet/index.d.ts

@@ -0,0 +1,56 @@
+/** The CIP-30 API a dApp gets from `window.cardano[key].enable()` (plus the CIP-95/CIP-103 extensions). */
+export interface WalletApi {
+    getUtxos: () => Promise<string[] | null | undefined>;
+    getCollateral?: () => Promise<string[] | null>;
+    getExtensions?: () => Promise<{
+        cip: number;
+    }[]>;
+    getBalance: () => Promise<string>;
+    getNetworkId: () => Promise<number>;
+    getRewardAddresses: () => Promise<string[]>;
+    getChangeAddress: () => Promise<string>;
+    getUsedAddresses: () => Promise<string[]>;
+    getUnusedAddresses: () => Promise<string[]>;
+    signTx: (tx: string, partialSign?: boolean) => Promise<string>;
+    submitTx: (tx: string) => Promise<string>;
+    cip95?: {
+        getPubDRepKey: () => Promise<string>;
+    };
+    cip103?: {
+        signTxs: (txs: {
+            cbor: string;
+            partialSign?: boolean;
+        }[]) => Promise<string[]>;
+        submitTxs: (txs: string[]) => Promise<(string | {
+            error: unknown;
+        })[]>;
+    };
+}
+export interface WalletUtxoAsset {
+    policyId: string;
+    /** Asset name, hex (CIP-68 label included). */
+    hex: string;
+    count: number;
+}
+export interface ParsedUtxo {
+    /** The wallet's CBOR, untouched (ship this to a backend, never a re-encoding). */
+    cbor: string;
+    /** `<txHash>#<index>` */
+    id: string;
+    lovelace: bigint;
+    assets: WalletUtxoAsset[];
+}
+/**
+ * Parse one CIP-30 `getUtxos()` entry (`[input, output]` CBOR). Handles legacy array-form and
+ * Babbage map-form outputs (inline datum, reference script). Returns null for anything that is not
+ * a valid TransactionUnspentOutput, so one malformed entry never hides the rest of the wallet.
+ */
+export declare const parseUtxo: (cborHex: string) => ParsedUtxo | null;
+/** Lovelace in a CIP-30 `getBalance()` result (a CBOR `Value`: bare coin or `[coin, multiasset]`). Throws on malformed input. */
+export declare const lovelaceFromBalance: (balanceCborHex: string) => bigint;
+/**
+ * CIP-30 returns addresses as hex bytes. Shelley addresses (base, enterprise, pointer, reward) are
+ * returned in bech32 with the network's prefix; Byron addresses in base58. '' for empty input;
+ * throws on bytes that are not an address.
+ */
+export declare const addressHexToBech32: (addressHex: string) => string;

package/wallet/index.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addressHexToBech32 = exports.lovelaceFromBalance = exports.parseUtxo = void 0;
+// Subpath module: `@koralabs/kora-labs-common/wallet`. Isomorphic (browser + Node), no network.
+// Reads what a CIP-30 wallet returns (UTxO CBOR, balance CBOR, address hex) with
+// @cardano-sdk/core Serialization — never a hand-rolled or generic CBOR decoder.
+const core_1 = require("@cardano-sdk/core");
+const POLICY_ID_HEX_LENGTH = 56;
+const HexBlob = (hex) => hex;
+/**
+ * Parse one CIP-30 `getUtxos()` entry (`[input, output]` CBOR). Handles legacy array-form and
+ * Babbage map-form outputs (inline datum, reference script). Returns null for anything that is not
+ * a valid TransactionUnspentOutput, so one malformed entry never hides the rest of the wallet.
+ */
+const parseUtxo = (cborHex) => {
+    var _a;
+    const cbor = cborHex === null || cborHex === void 0 ? void 0 : cborHex.trim();
+    if (!cbor)
+        return null;
+    try {
+        const utxo = core_1.Serialization.TransactionUnspentOutput.fromCbor(HexBlob(cbor));
+        const input = utxo.input();
+        const value = utxo.output().amount();
+        const assets = [];
+        for (const [assetId, quantity] of (_a = value.multiasset()) !== null && _a !== void 0 ? _a : new Map()) {
+            assets.push({
+                policyId: assetId.slice(0, POLICY_ID_HEX_LENGTH),
+                hex: assetId.slice(POLICY_ID_HEX_LENGTH),
+                count: Number(quantity)
+            });
+        }
+        return { cbor, id: `${input.transactionId()}#${input.index()}`, lovelace: value.coin(), assets };
+    }
+    catch (_b) {
+        return null;
+    }
+};
+exports.parseUtxo = parseUtxo;
+/** Lovelace in a CIP-30 `getBalance()` result (a CBOR `Value`: bare coin or `[coin, multiasset]`). Throws on malformed input. */
+const lovelaceFromBalance = (balanceCborHex) => core_1.Serialization.Value.fromCbor(HexBlob(balanceCborHex)).coin();
+exports.lovelaceFromBalance = lovelaceFromBalance;
+/**
+ * CIP-30 returns addresses as hex bytes. Shelley addresses (base, enterprise, pointer, reward) are
+ * returned in bech32 with the network's prefix; Byron addresses in base58. '' for empty input;
+ * throws on bytes that are not an address.
+ */
+const addressHexToBech32 = (addressHex) => {
+    const hex = (addressHex !== null && addressHex !== void 0 ? addressHex : '').replace(/^0x/i, '');
+    if (!hex)
+        return '';
+    const address = core_1.Cardano.Address.fromBytes(HexBlob(hex));
+    return address.getType() === core_1.Cardano.AddressType.Byron ? address.toBase58() : address.toBech32();
+};
+exports.addressHexToBech32 = addressHexToBech32;