@koralabs/kora-labs-common 6.11.0 → 6.13.0

package/chain/config.js

@@ -26,10 +26,20 @@ const chainConfigFromEnv = (env = process.env) => {
         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
+        apiHost: ((_d = env.HANDLE_API_ENDPOINT) === null || _d === void 0 ? void 0 : _d.trim()) || undefined,
+        apiHeaders: buildApiHeaders(env)
     });
 };
 exports.chainConfigFromEnv = chainConfigFromEnv;
+const buildApiHeaders = (env) => {
+    var _a, _b;
+    const headers = {};
+    if ((_a = env.HANDLE_ME_API_KEY) === null || _a === void 0 ? void 0 : _a.trim())
+        headers['api-key'] = env.HANDLE_ME_API_KEY.trim();
+    if ((_b = env.KORA_USER_AGENT) === null || _b === void 0 ? void 0 : _b.trim())
+        headers['User-Agent'] = env.KORA_USER_AGENT.trim();
+    return Object.keys(headers).length ? headers : undefined;
+};
 /**
  * Factory for the default read-failover provider set: Koios + Blockfrost, mutually redundant.
  */

package/chain/datum/imageDatum.d.ts

@@ -1,7 +1,13 @@
 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 interface DatumDecodeOptions {
+    /** Extra request headers (e.g. api-key, User-Agent) required by the Handles API /datum endpoint. */
+    headers?: Record<string, string>;
+    /** Injectable fetch for tests; defaults to the runtime global fetch. */
+    fetcher?: (url: string, init?: any) => Promise<{
+        text: () => Promise<string>;
+    }>;
+}
+export declare const decodeDatumViaApi: <T>(apiHost: string, datum: string, schema?: Record<string, unknown>, options?: DatumDecodeOptions) => Promise<T>;
 export declare const decode0xHexToUtf8: (v: unknown) => unknown;
 export declare const normalizeCreatorDefaultTextFields: (creatorDefaults: Record<string, unknown>) => void;
 export interface ImageDatumDetails {
@@ -9,6 +15,4 @@ export interface ImageDatumDetails {
     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>;
+export declare const getImageDataFromDatum: (apiHost: string, datum: string, options?: DatumDecodeOptions) => Promise<ImageDatumDetails>;

package/chain/datum/imageDatum.js

@@ -6,10 +6,12 @@ exports.getImageDataFromDatum = exports.normalizeCreatorDefaultTextFields = expo
 // 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 decodeDatumViaApi = async (apiHost, datum, schema, options = {}) => {
+    var _a, _b;
+    const fetcher = (_a = options.fetcher) !== null && _a !== void 0 ? _a : defaultFetch;
     const response = await fetcher(`${apiHost}/datum?from=plutus_data_cbor&to=json`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...((_b = options.headers) !== null && _b !== void 0 ? _b : {}) },
         body: JSON.stringify({ cbor: datum, schema })
     });
     const text = await response.text();
@@ -53,7 +55,7 @@ const normalizeCreatorDefaultTextFields = (creatorDefaults) => {
     }
 };
 exports.normalizeCreatorDefaultTextFields = normalizeCreatorDefaultTextFields;
-const getImageDataFromDatum = async (apiHost, datum, fetcher) => {
+const getImageDataFromDatum = async (apiHost, datum, options) => {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     let decodedDatum;
     try {
@@ -70,7 +72,7 @@ const getImageDataFromDatum = async (apiHost, datum, fetcher) => {
                     qr_image: 'string'
                 }
             }
-        }, fetcher);
+        }, options);
     }
     catch (_j) {
         return { image: '' };

package/chain/providerConfig.d.ts

@@ -16,6 +16,12 @@ export interface ChainProviderConfig {
      * critical — do NOT swap it for a local CBOR decode without matching that behavior.
      */
     apiHost?: string;
+    /**
+     * Extra headers sent with the datum-decode POST to `apiHost` (e.g. `api-key`, `User-Agent`).
+     * Required when the Handles API gates `/datum` by api-key — omitting them silently changes
+     * datum-decode behavior. `chainConfigFromEnv` populates these from HANDLE_ME_API_KEY / KORA_USER_AGENT.
+     */
+    apiHeaders?: Record<string, string>;
 }
 export declare const normalizeNetwork: (network: string) => string;
 /** Public api.handle.me host for a network (mainnet has no subdomain prefix). */

package/chain/providers/Blockfrost.js

@@ -118,7 +118,9 @@ class Blockfrost {
             : hex;
         const datum = await this.getAssetDatum(policyId, updateHex);
         if (datum) {
-            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum);
+            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum, {
+                headers: this.config.apiHeaders
+            });
         }
         let image = '';
         if ((data === null || data === void 0 ? void 0 : data.onchain_metadata) && (data === null || data === void 0 ? void 0 : data.onchain_metadata.image)) {

package/chain/providers/Koios.js

@@ -180,7 +180,9 @@ class Koios {
         if (metadata && metadata.image)
             image = metadata.image;
         if (datum) {
-            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum);
+            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum, {
+                headers: this.config.apiHeaders
+            });
         }
         return { image, metadata };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.11.0",
+    "version": "6.13.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",
@@ -40,11 +40,15 @@
         "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
         "@aws-sdk/client-dynamodb": "^3.549.0",
         "@aws-sdk/lib-dynamodb": "^3.549.0",
+        "@cardano-sdk/core": "^0.46.15",
+        "@cardano-sdk/crypto": "^0.4.7",
+        "@emurgo/cardano-message-signing-nodejs": "^1.1.0",
         "@types/jest": "^30.0.0",
         "@types/node": "^22.15.17",
         "@types/pluralize": "^0.0.29",
         "@typescript-eslint/eslint-plugin": "^8.67.0",
         "@typescript-eslint/parser": "^8.67.0",
+        "bip39": "^3.1.0",
         "eslint": "^8.57.1",
         "jest": "^30.4.2",
         "ts-jest": "^29.4.11",
@@ -67,11 +71,27 @@
         "brace-expansion": "5.0.9"
     },
     "peerDependencies": {
-        "@aiken-lang/merkle-patricia-forestry": "^1.2.0"
+        "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
+        "@cardano-sdk/core": "^0.46.12",
+        "@cardano-sdk/crypto": "^0.4.5",
+        "bip39": "^3.1.0",
+        "@emurgo/cardano-message-signing-nodejs": "^1.1.0"
     },
     "peerDependenciesMeta": {
         "@aiken-lang/merkle-patricia-forestry": {
             "optional": true
+        },
+        "@cardano-sdk/core": {
+            "optional": true
+        },
+        "@cardano-sdk/crypto": {
+            "optional": true
+        },
+        "bip39": {
+            "optional": true
+        },
+        "@emurgo/cardano-message-signing-nodejs": {
+            "optional": true
         }
     }
 }

package/testing/index.d.ts

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

package/testing/index.js

@@ -0,0 +1,23 @@
+"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 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("./liveWallet"), exports);
+__exportStar(require("./installWallet"), exports);
+__exportStar(require("./readOnlyGuard"), exports);
+__exportStar(require("./onChain"), exports);

package/testing/installWallet.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bridges a Node-side `LiveWallet` into browser pages as `window.cardano[walletKey]`.
+ *
+ * The bridge is exposed at BROWSER-CONTEXT level so it also exists on cross-origin pages the flow
+ * navigates to (e.g. auth.handle.me OAuth), not just the first origin. Typed structurally so this
+ * module does not depend on @playwright/test.
+ */
+import type { LiveWallet } from './liveWallet';
+export interface PageLike {
+    context(): {
+        exposeFunction(name: string, callback: (...args: any[]) => unknown): Promise<void>;
+    };
+    addInitScript(script: {
+        content: string;
+    }): Promise<void>;
+}
+export interface InstallWalletOptions {
+    walletKey?: string;
+    walletName?: string;
+}
+export declare const DEFAULT_WALLET_KEY = "handleLiveE2E";
+export declare const DEFAULT_WALLET_NAME = "Handle Live E2E";
+export declare const BRIDGE_FUNCTION = "__liveCip30Call";
+/** Browser-side init script. Exported so it can be exercised without a browser. */
+export declare const buildCip30InitScript: ({ walletKey, walletName }?: InstallWalletOptions) => string;
+/** Node side of the bridge: JSON in, JSON out (so errors and bigints never cross as live objects). */
+export declare const createBridgeHandler: (wallet: LiveWallet) => (method: string, paramsJson: string) => Promise<string>;
+export declare const installLiveCip30Wallet: (page: PageLike, wallet: LiveWallet, options?: InstallWalletOptions) => Promise<void>;

package/testing/installWallet.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installLiveCip30Wallet = exports.createBridgeHandler = exports.buildCip30InitScript = exports.BRIDGE_FUNCTION = exports.DEFAULT_WALLET_NAME = exports.DEFAULT_WALLET_KEY = void 0;
+exports.DEFAULT_WALLET_KEY = 'handleLiveE2E';
+exports.DEFAULT_WALLET_NAME = 'Handle Live E2E';
+exports.BRIDGE_FUNCTION = '__liveCip30Call';
+const WALLET_ICON = 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"%3E%3Ccircle cx="12" cy="12" r="10" fill="%234da965"/%3E%3C/svg%3E';
+/** Browser-side init script. Exported so it can be exercised without a browser. */
+const buildCip30InitScript = ({ walletKey = exports.DEFAULT_WALLET_KEY, walletName = exports.DEFAULT_WALLET_NAME } = {}) => `
+(function() {
+    const call = async (method, params) => {
+        if (typeof window.${exports.BRIDGE_FUNCTION} !== 'function') throw new Error('${exports.BRIDGE_FUNCTION} bridge not available');
+        return JSON.parse(await window.${exports.BRIDGE_FUNCTION}(method, JSON.stringify(params === undefined ? null : params)));
+    };
+    const api = {
+        getUtxos: () => call('getUtxos'),
+        getCollateral: (params) => call('getCollateral', params),
+        getBalance: () => call('getBalance'),
+        getNetworkId: () => call('getNetworkId'),
+        getRewardAddresses: () => call('getRewardAddresses'),
+        getChangeAddress: () => call('getChangeAddress'),
+        getUsedAddresses: () => call('getUsedAddresses'),
+        getUnusedAddresses: () => call('getUnusedAddresses'),
+        getExtensions: () => call('getExtensions'),
+        signTx: (tx) => call('signTx', tx),
+        signData: (addr, payload) => call('signData', { addr, payload }),
+        submitTx: (tx) => call('submitTx', tx),
+        cip95: { getPubDRepKey: () => call('getPubDRepKey') },
+        cip103: { signTxs: (txs) => call('signTxs', txs) }
+    };
+    const cardano = (window.cardano = window.cardano || {});
+    cardano[${JSON.stringify(walletKey)}] = {
+        name: ${JSON.stringify(walletName)},
+        icon: ${JSON.stringify(WALLET_ICON)},
+        apiVersion: '1.1.0',
+        supportedExtensions: [{ cip: 8 }, { cip: 95 }, { cip: 103 }],
+        isEnabled: async () => true,
+        enable: async () => api
+    };
+})();
+`;
+exports.buildCip30InitScript = buildCip30InitScript;
+/** Node side of the bridge: JSON in, JSON out (so errors and bigints never cross as live objects). */
+const createBridgeHandler = (wallet) => async (method, paramsJson) => JSON.stringify(await wallet.call(method, JSON.parse(paramsJson)));
+exports.createBridgeHandler = createBridgeHandler;
+const installLiveCip30Wallet = async (page, wallet, options = {}) => {
+    try {
+        await page.context().exposeFunction(exports.BRIDGE_FUNCTION, (0, exports.createBridgeHandler)(wallet));
+    }
+    catch (error) {
+        // A reused context already has the binding; anything else is a real failure.
+        if (!/has been already registered/i.test(error.message))
+            throw error;
+    }
+    await page.addInitScript({ content: (0, exports.buildCip30InitScript)(options) });
+};
+exports.installLiveCip30Wallet = installLiveCip30Wallet;

package/testing/liveWallet.d.ts

@@ -0,0 +1,27 @@
+export type LiveNetwork = 'preview' | 'preprod' | 'mainnet';
+export interface LiveWalletConfig {
+    mnemonic: string;
+    network: LiveNetwork;
+    blockfrostApiKey: string;
+    /** CIP-1852 account index (m/1852'/1815'/<account>'). Separate suites should use separate accounts so they never contend for UTxOs. */
+    accountIndex?: number;
+    /** When set, every submitted signed tx is written here for post-mortem. */
+    submitDumpDir?: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+export interface LiveWallet {
+    address: string;
+    addressHex: string;
+    rewardAddress: string;
+    rewardAddressHex: string;
+    networkId: number;
+    paymentKeyHash: string;
+    stakeKeyHash: string;
+    dRepId: string;
+    call: (method: string, params?: unknown) => Promise<unknown>;
+    submittedTxHashes: string[];
+    countUtxos: () => Promise<number>;
+}
+export declare const blockfrostBaseUrl: (network: LiveNetwork) => string;
+export declare const createLiveWallet: (config: LiveWalletConfig) => Promise<LiveWallet>;

package/testing/liveWallet.js

@@ -0,0 +1,285 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLiveWallet = exports.blockfrostBaseUrl = 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),
+ *   - 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).
+ * Runs in Node; bridge it into a page with `installLiveCip30Wallet`.
+ */
+const blakejs_1 = require("blakejs");
+const bech32_1 = require("bech32");
+const tx_1 = require("../tx");
+const HARDENED = 0x80000000;
+let sdkPromise = null;
+// @cardano-sdk/crypto ships its own nested libsodium-wrappers-sumo; it must be `ready` before any
+// Bip32 operation or it throws "libsodium was not correctly initialized".
+const loadSdk = () => {
+    sdkPromise !== null && sdkPromise !== void 0 ? sdkPromise : (sdkPromise = (async () => {
+        const cryptoDir = require.resolve('@cardano-sdk/crypto').replace(/\/dist\/.*/, '');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const sodium = require(require.resolve('libsodium-wrappers-sumo', { paths: [cryptoDir] }));
+        await sodium.ready;
+        const core = await Promise.resolve().then(() => __importStar(require('@cardano-sdk/core')));
+        // Conway set tagging (tag 258) is required for valid tx CBOR on Conway networks.
+        core.setInConwayEra(true);
+        const Crypto = await Promise.resolve().then(() => __importStar(require('@cardano-sdk/crypto')));
+        const bip39 = await Promise.resolve().then(() => __importStar(require('bip39')));
+        return { Cardano: core.Cardano, Serialization: core.Serialization, Crypto, bip39 };
+    })());
+    return sdkPromise;
+};
+const blockfrostBaseUrl = (network) => `https://cardano-${network}.blockfrost.io/api/v0`;
+exports.blockfrostBaseUrl = blockfrostBaseUrl;
+const createLiveWallet = async (config) => {
+    var _a, _b;
+    const { Cardano, Serialization, Crypto, bip39 } = await loadSdk();
+    const doFetch = (_a = config.fetchFn) !== null && _a !== void 0 ? _a : fetch;
+    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 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();
+    const stakeKey = accountKey.derive([2, 0]).toRawKey();
+    const paymentKeyHash = paymentKey.toPublic().hash().hex();
+    const stakeKeyHash = stakeKey.toPublic().hash().hex();
+    const paymentCredential = { type: Cardano.CredentialType.KeyHash, hash: paymentKeyHash };
+    const stakeCredential = { type: Cardano.CredentialType.KeyHash, hash: stakeKeyHash };
+    const baseAddress = Cardano.BaseAddress.fromCredentials(networkId, paymentCredential, stakeCredential).toAddress();
+    const address = baseAddress.toBech32();
+    const addressHex = baseAddress.toBytes();
+    // Some handle.me flows park tokens at EnterpriseAddress(stakeCredential); a real wallet owning
+    // the stake key reports those UTxOs too.
+    const enterpriseStakeAddress = Cardano.EnterpriseAddress.fromCredentials(networkId, stakeCredential).toAddress().toBech32();
+    const rewardAddress = Cardano.RewardAccount.fromCredential(stakeCredential, networkId);
+    const rewardAddressHex = Cardano.Address.fromString(rewardAddress).toBytes();
+    // CIP-95: DRep id = bech32('drep', 0x22 || blake2b-224(pubkey)).
+    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 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 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)
+                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);
+            if (batch.length < 100)
+                break;
+        }
+        return all;
+    };
+    const utxoToCborHex = (u) => {
+        var _a, _b, _c;
+        const coins = BigInt((_b = (_a = u.amount.find((a) => a.unit === 'lovelace')) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0');
+        const assets = new Map();
+        for (const a of u.amount)
+            if (a.unit !== 'lovelace')
+                assets.set(a.unit, BigInt(a.quantity));
+        const output = {
+            address: (_c = u._sourceAddr) !== null && _c !== void 0 ? _c : address,
+            value: { coins, ...(assets.size > 0 ? { assets } : {}) },
+            ...(u.inline_datum ? { datum: Serialization.PlutusData.fromCbor(u.inline_datum).toCore() } : {}),
+            ...(!u.inline_datum && u.data_hash ? { datumHash: u.data_hash } : {})
+        };
+        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);
+    };
+    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));
+        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)).
+    const needsStakeKeySignature = async (body) => {
+        var _a, _b, _c, _d;
+        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;
+    };
+    const signTx = async (txCborHex) => {
+        (0, tx_1.assertCanonicalCbor)(txCborHex, 'signTx');
+        const tx = Serialization.Transaction.fromCbor(txCborHex);
+        const bodyHash = tx.body().hash();
+        const signatures = new Map();
+        signatures.set(paymentKey.toPublic().hex(), paymentKey.sign(bodyHash).hex());
+        if (await needsStakeKeySignature(tx.body().toCore())) {
+            signatures.set(stakeKey.toPublic().hex(), stakeKey.sign(bodyHash).hex());
+        }
+        return Serialization.TransactionWitnessSet.fromCore({ signatures }).toCbor();
+    };
+    const signTxs = async (txs) => {
+        var _a;
+        const out = [];
+        for (const entry of txs)
+            out.push(await signTx(typeof entry === 'string' ? entry : ((_a = entry.cbor) !== null && _a !== void 0 ? _a : entry.tx)));
+        return out;
+    };
+    const submitTx = async (signedTxCbor) => {
+        if (config.submitDumpDir) {
+            const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
+            const path = await Promise.resolve().then(() => __importStar(require('node:path')));
+            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}`);
+    };
+    // CIP-8 COSE_Sign1 over the payload with the payment key (CIP-30 signData).
+    const signData = async (addrHex, payloadHex) => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const cms = require('@emurgo/cardano-message-signing-nodejs');
+        const protectedHeaders = cms.HeaderMap.new();
+        protectedHeaders.set_algorithm_id(cms.Label.from_algorithm_id(cms.AlgorithmId.EdDSA));
+        protectedHeaders.set_header(cms.Label.new_text('address'), cms.CBORValue.new_bytes(Buffer.from(addrHex, 'hex')));
+        const headers = cms.Headers.new(cms.ProtectedHeaderMap.new(protectedHeaders), cms.HeaderMap.new());
+        const builder = cms.COSESign1Builder.new(headers, Buffer.from(payloadHex, 'hex'), false);
+        const toSign = Buffer.from(builder.make_data_to_sign().to_bytes()).toString('hex');
+        const coseSign1 = builder.build(Buffer.from(paymentKey.sign(toSign).hex(), 'hex'));
+        const coseKey = cms.COSEKey.new(cms.Label.from_key_type(cms.KeyType.OKP));
+        coseKey.set_algorithm_id(cms.Label.from_algorithm_id(cms.AlgorithmId.EdDSA));
+        coseKey.set_header(cms.Label.new_int(cms.Int.new_i32(-1)), cms.CBORValue.from_label(cms.Label.from_curve_type(cms.CurveType.Ed25519)));
+        coseKey.set_header(cms.Label.new_int(cms.Int.new_i32(-2)), cms.CBORValue.new_bytes(Buffer.from(paymentKey.toPublic().hex(), 'hex')));
+        return {
+            signature: Buffer.from(coseSign1.to_bytes()).toString('hex'),
+            key: Buffer.from(coseKey.to_bytes()).toString('hex')
+        };
+    };
+    const call = async (method, params) => {
+        switch (method) {
+            case 'getUtxos':
+                return getUtxos();
+            case 'getCollateral':
+                return null;
+            case 'getBalance':
+                return getBalance();
+            case 'getNetworkId':
+                return networkId;
+            case 'getRewardAddresses':
+                return [rewardAddressHex];
+            case 'getChangeAddress':
+                return addressHex;
+            case 'getUsedAddresses':
+                return [addressHex];
+            case 'getUnusedAddresses':
+                return [];
+            case 'getExtensions':
+                return [{ cip: 8 }, { cip: 95 }, { cip: 103 }];
+            case 'signTx':
+                return signTx(params);
+            case 'signTxs':
+                return signTxs(params);
+            case 'signData': {
+                const p = params;
+                return signData(p.addr, p.payload);
+            }
+            case 'submitTx':
+                return submitTx(params);
+            case 'getPubDRepKey':
+                return dRepPubKeyHex;
+            default:
+                throw new Error(`Unknown CIP-30 method: ${method}`);
+        }
+    };
+    return {
+        address,
+        addressHex,
+        rewardAddress,
+        rewardAddressHex,
+        networkId,
+        paymentKeyHash,
+        stakeKeyHash,
+        dRepId,
+        call,
+        submittedTxHashes,
+        countUtxos: async () => (await fetchAddressUtxos(address)).length
+    };
+};
+exports.createLiveWallet = createLiveWallet;

package/testing/onChain.d.ts

@@ -0,0 +1,58 @@
+import { LiveNetwork } from './liveWallet';
+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 interface TxUtxoOutput {
+    address: string;
+    amount: {
+        unit: string;
+        quantity: string;
+    }[];
+    output_index: number;
+    inline_datum?: string | null;
+    data_hash?: string | null;
+    consumed_by_tx?: string | null;
+}
+export interface TxUtxos {
+    hash: string;
+    inputs: (TxUtxoOutput & {
+        tx_hash: string;
+    })[];
+    outputs: TxUtxoOutput[];
+}
+export declare const fetchTxUtxos: (chain: ChainConfig, txHash: string) => Promise<TxUtxos>;
+export declare const lovelaceOf: (amount: {
+    unit: string;
+    quantity: string;
+}[]) => bigint;
+export interface TxConfirmation {
+    confirmed: boolean;
+    block?: string;
+    validContract?: boolean;
+}
+/** Poll until the tx is in a block. A tx in a block with `valid_contract: false` is NOT a success. */
+export declare const waitForTxConfirmation: (chain: ChainConfig, txHash: string, timeoutMs?: number, pollMs?: number) => Promise<TxConfirmation>;
+/** Poll a tx output until it is spent; returns the spending tx hash, or null on timeout. */
+export declare const waitForOutputConsumed: (chain: ChainConfig, txHash: string, outputIndex: number, timeoutMs: number, pollMs?: number) => Promise<string | null>;
+/** Assert `<policy><label><name>` exists with quantity > 0 and, optionally, that another label does NOT exist. */
+export declare const assertCip68Label: (chain: ChainConfig, policyId: string, name: string, opts: {
+    hasLabel: string;
+    notLabel?: string;
+}) => Promise<void>;
+/** Assert an asset's total on-chain quantity is 0 (burned). */
+export declare const assertAssetBurned: (chain: ChainConfig, assetUnit: string) => Promise<void>;
+/** Assert a tx paid at least `minLovelace` (summed over outputs) to `toAddress`. */
+export declare const assertAdaTransfer: (chain: ChainConfig, txHash: string, toAddress: string, minLovelace: bigint) => Promise<bigint>;
+/** Resolve an output's datum CBOR hex (inline, or by hash). */
+export declare const fetchOutputDatumCbor: (chain: ChainConfig, output: TxUtxoOutput) => Promise<string>;
+/** Decode the CIP-68 `extra` map (constr field 2) from the output of `txHash` that holds `<label><name>`. */
+export declare const fetchCip68ExtraFromTx: (chain: ChainConfig, txHash: string, name: string, label?: string) => Promise<Map<Buffer, unknown>>;
+/** Read a scalar field from a decoded CIP-68 map (metadata or extra). */
+export declare const cip68Field: (map: Map<Buffer, unknown>, key: string) => string | null;

package/testing/onChain.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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.
+ */
+const cbor_1 = __importDefault(require("cbor"));
+const liveWallet_1 = require("./liveWallet");
+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 fetchTxUtxos = (chain, txHash) => getJson(chain, `/txs/${txHash}/utxos`);
+exports.fetchTxUtxos = fetchTxUtxos;
+const lovelaceOf = (amount) => { var _a, _b; return BigInt((_b = (_a = amount.find((a) => a.unit === 'lovelace')) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0'); };
+exports.lovelaceOf = lovelaceOf;
+/** Poll until the tx is in a block. A tx in a block with `valid_contract: false` is NOT a success. */
+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());
+            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));
+    }
+};
+exports.waitForTxConfirmation = waitForTxConfirmation;
+/** Poll a tx output until it is spent; returns the spending tx hash, or null on timeout. */
+const waitForOutputConsumed = async (chain, txHash, outputIndex, timeoutMs, pollMs = 15000) => {
+    const start = Date.now();
+    for (;;) {
+        const utxos = await (0, exports.fetchTxUtxos)(chain, txHash);
+        const out = utxos.outputs.find((o) => o.output_index === outputIndex);
+        if (!out)
+            throw new Error(`onChain: ${txHash}#${outputIndex} does not exist`);
+        if (out.consumed_by_tx)
+            return out.consumed_by_tx;
+        if (Date.now() - start >= timeoutMs)
+            return null;
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+};
+exports.waitForOutputConsumed = waitForOutputConsumed;
+/** Assert `<policy><label><name>` exists with quantity > 0 and, optionally, that another label does NOT exist. */
+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');
+    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})`);
+        }
+    }
+};
+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)
+        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';
+    if (BigInt(quantity) !== BigInt(0))
+        throw new Error(`onChain: expected ${assetUnit} burned, quantity is ${quantity}`);
+};
+exports.assertAssetBurned = assertAssetBurned;
+/** Assert a tx paid at least `minLovelace` (summed over outputs) to `toAddress`. */
+const assertAdaTransfer = async (chain, txHash, toAddress, minLovelace) => {
+    const { outputs } = await (0, exports.fetchTxUtxos)(chain, txHash);
+    const paid = outputs.filter((o) => o.address === toAddress).reduce((sum, o) => sum + (0, exports.lovelaceOf)(o.amount), BigInt(0));
+    if (paid < minLovelace)
+        throw new Error(`onChain: tx ${txHash} paid ${paid} lovelace to ${toAddress}, expected >= ${minLovelace}`);
+    return paid;
+};
+exports.assertAdaTransfer = assertAdaTransfer;
+/** Resolve an output's datum CBOR hex (inline, or by hash). */
+const fetchOutputDatumCbor = async (chain, output) => {
+    if (output.inline_datum)
+        return output.inline_datum;
+    if (output.data_hash)
+        return (await getJson(chain, `/scripts/datum/${output.data_hash}/cbor`)).cbor;
+    throw new Error(`onChain: output #${output.output_index} carries no datum`);
+};
+exports.fetchOutputDatumCbor = fetchOutputDatumCbor;
+/** Decode the CIP-68 `extra` map (constr field 2) from the output of `txHash` that holds `<label><name>`. */
+const fetchCip68ExtraFromTx = async (chain, txHash, name, label = exports.LBL_100) => {
+    var _a;
+    const { outputs } = await (0, exports.fetchTxUtxos)(chain, txHash);
+    const suffix = `${label}${(0, exports.hexOf)(name)}`;
+    const out = outputs.find((o) => o.amount.some((a) => a.unit.endsWith(suffix)));
+    if (!out)
+        throw new Error(`onChain: no ${label} output for ${name} in ${txHash}`);
+    const decoded = cbor_1.default.decodeFirstSync(Buffer.from(await (0, exports.fetchOutputDatumCbor)(chain, out), 'hex'));
+    const extra = (_a = decoded.value) === null || _a === void 0 ? void 0 : _a[2];
+    if (!(extra instanceof Map))
+        throw new Error('onChain: CIP-68 datum has no extra map');
+    return extra;
+};
+exports.fetchCip68ExtraFromTx = fetchCip68ExtraFromTx;
+/** Read a scalar field from a decoded CIP-68 map (metadata or extra). */
+const cip68Field = (map, key) => {
+    for (const [k, v] of map.entries()) {
+        if (!Buffer.isBuffer(k) || k.toString('utf8') !== key)
+            continue;
+        if (Buffer.isBuffer(v))
+            return v.toString('utf8');
+        if (v == null)
+            return null;
+        if (v instanceof Map || Array.isArray(v))
+            return JSON.stringify(v);
+        return String(v);
+    }
+    return null;
+};
+exports.cip68Field = cip68Field;

package/testing/readOnlyGuard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read-only wallet guard for MAINNET smoke suites.
+ *
+ * Wraps a real LiveWallet so it is physically unable to move funds: signTx / signTxs / submitTx
+ * are recorded and THROWN. Everything else (getUtxos, signData for OAuth, ...) passes through.
+ * A scope proves it reached the transaction by asserting `reachedSign()` — the app built a tx and
+ * asked to sign it — and stops there.
+ */
+import type { LiveWallet } from './liveWallet';
+export declare const FUND_MOVING_METHODS: readonly ["signTx", "signTxs", "submitTx"];
+export declare const READ_ONLY_GUARD_ERROR = "E2E_READONLY_GUARD";
+export interface SignRequest {
+    method: (typeof FUND_MOVING_METHODS)[number];
+    at: number;
+    /** The exact tx CBOR the app asked to sign (first tx for signTxs). Decode it to assert what would have been signed. */
+    txCbor: string;
+}
+export interface ReadOnlyWallet {
+    wallet: LiveWallet;
+    signRequests: SignRequest[];
+    reachedSign(): boolean;
+    reset(): void;
+    waitForSignRequest(timeoutMs: number, tick?: () => Promise<unknown>): Promise<boolean>;
+}
+export declare const makeReadOnlyWallet: (inner: LiveWallet) => ReadOnlyWallet;

package/testing/readOnlyGuard.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeReadOnlyWallet = exports.READ_ONLY_GUARD_ERROR = exports.FUND_MOVING_METHODS = void 0;
+exports.FUND_MOVING_METHODS = ['signTx', 'signTxs', 'submitTx'];
+exports.READ_ONLY_GUARD_ERROR = 'E2E_READONLY_GUARD';
+const firstTxCbor = (params) => {
+    var _a, _b;
+    if (typeof params === 'string')
+        return params;
+    if (Array.isArray(params)) {
+        const first = params[0];
+        return typeof first === 'string' ? first : ((_b = (_a = first === null || first === void 0 ? void 0 : first.cbor) !== null && _a !== void 0 ? _a : first === null || first === void 0 ? void 0 : first.tx) !== null && _b !== void 0 ? _b : '');
+    }
+    return '';
+};
+const makeReadOnlyWallet = (inner) => {
+    const signRequests = [];
+    const guardedCall = async (method, params) => {
+        if (exports.FUND_MOVING_METHODS.includes(method)) {
+            signRequests.push({ method: method, at: Date.now(), txCbor: firstTxCbor(params) });
+            throw new Error(`${exports.READ_ONLY_GUARD_ERROR}: '${method}' is blocked — this suite reaches the transaction and stops; it never signs or submits.`);
+        }
+        return inner.call(method, params);
+    };
+    return {
+        wallet: { ...inner, call: guardedCall },
+        signRequests,
+        reachedSign: () => signRequests.length > 0,
+        reset: () => {
+            signRequests.length = 0;
+        },
+        waitForSignRequest: async (timeoutMs, tick) => {
+            const start = Date.now();
+            while (signRequests.length === 0 && Date.now() - start < timeoutMs) {
+                if (tick)
+                    await tick();
+                await new Promise((r) => setTimeout(r, 1500));
+            }
+            return signRequests.length > 0;
+        }
+    };
+};
+exports.makeReadOnlyWallet = makeReadOnlyWallet;

package/tx/cbor.d.ts

@@ -0,0 +1,38 @@
+export interface CborHeader {
+    majorType: number;
+    additionalInfo: number;
+    length: number;
+    headerEnd: number;
+}
+export declare const readCborHeader: (buf: Uint8Array, start: number) => CborHeader;
+/** Return the offset immediately after the CBOR item starting at `start`. */
+export declare const skipCborItem: (buf: Uint8Array, start: number) => number;
+/** Byte span of the witness set (element 1) inside `transaction = [body, witness_set, is_valid, aux]`. */
+export declare const locateWitnessSet: (txBytes: Uint8Array) => {
+    start: number;
+    end: number;
+};
+/** Byte span of the transaction body (element 0). The tx id is blake2b-256 over exactly these bytes. */
+export declare const locateTxBody: (txBytes: Uint8Array) => {
+    start: number;
+    end: number;
+};
+/**
+ * Merge a CIP-30 `signTx(tx, partialSign=true)` witness set into the unsigned tx WITHOUT
+ * re-encoding the body or any non-vkey witness entry (scripts, redeemers, datums stay
+ * byte-identical). Existing real vkey witnesses (e.g. a backend policy pre-sign) are preserved;
+ * fee-estimation placeholders are dropped.
+ */
+export declare const mergeWitnessSet: (unsignedTxHex: string, walletWitnessSetHex: string) => string;
+export interface CanonicalViolation {
+    path: string;
+    detail: string;
+}
+/**
+ * Canonical-CBOR check (CIP-21 key order) for the transaction-structure maps only: the body map
+ * (tx[0]) and the witness map (tx[1]). Hardware wallets and Eternl reject a tx whose structure maps
+ * are out of canonical order. Plutus data and multi-asset maps are deliberately NOT checked — they
+ * are hashed as-is and canonicalizing them would change hashes.
+ */
+export declare const findCanonicalCborViolations: (txHex: string) => CanonicalViolation[];
+export declare const assertCanonicalCbor: (txHex: string, label?: string) => void;

package/tx/cbor.js

@@ -0,0 +1,275 @@
+"use strict";
+// Byte-level CBOR helpers for signed-transaction assembly. Pure functions, no deps beyond Buffer,
+// so they are safe in the browser (wallet contexts) and in Node (test harnesses).
+//
+// Why byte-level: decoding a built tx into an SDK object and re-encoding it can change bytes
+// (definite vs indefinite arrays, integer widths, key order). The node hashes the exact bytes it
+// receives, so any re-encode after the backend computed script_data_hash / the body hash breaks
+// the tx (PPViewHashesDontMatch, or a signature over a body that no longer exists).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertCanonicalCbor = exports.findCanonicalCborViolations = exports.mergeWitnessSet = exports.locateTxBody = exports.locateWitnessSet = exports.skipCborItem = exports.readCborHeader = void 0;
+const readCborHeader = (buf, start) => {
+    const majorType = buf[start] >> 5;
+    const additionalInfo = buf[start] & 0x1f;
+    let headerEnd = start + 1;
+    let length = additionalInfo;
+    if (additionalInfo === 24) {
+        length = buf[start + 1];
+        headerEnd = start + 2;
+    }
+    else if (additionalInfo === 25) {
+        length = (buf[start + 1] << 8) | buf[start + 2];
+        headerEnd = start + 3;
+    }
+    else if (additionalInfo === 26) {
+        length = buf[start + 1] * 0x1000000 + ((buf[start + 2] << 16) | (buf[start + 3] << 8) | buf[start + 4]);
+        headerEnd = start + 5;
+    }
+    else if (additionalInfo === 27) {
+        let v = 0;
+        for (let i = 0; i < 8; i++)
+            v = v * 256 + buf[start + 1 + i];
+        length = v;
+        headerEnd = start + 9;
+    }
+    else if (additionalInfo >= 28 && additionalInfo <= 30) {
+        throw new Error(`Unsupported CBOR additional info ${additionalInfo} at byte ${start}`);
+    }
+    return { majorType, additionalInfo, length, headerEnd };
+};
+exports.readCborHeader = readCborHeader;
+/** Return the offset immediately after the CBOR item starting at `start`. */
+const skipCborItem = (buf, start) => {
+    const { majorType, additionalInfo, length, headerEnd } = (0, exports.readCborHeader)(buf, start);
+    if (additionalInfo === 31) {
+        let c = headerEnd;
+        while (buf[c] !== 0xff) {
+            c = (0, exports.skipCborItem)(buf, c);
+            if (majorType === 5)
+                c = (0, exports.skipCborItem)(buf, c);
+        }
+        return c + 1;
+    }
+    if (majorType <= 1 || majorType === 7)
+        return headerEnd;
+    if (majorType === 2 || majorType === 3)
+        return headerEnd + length;
+    if (majorType === 6)
+        return (0, exports.skipCborItem)(buf, headerEnd);
+    let c = headerEnd;
+    const items = majorType === 5 ? length * 2 : length;
+    for (let i = 0; i < items; i++)
+        c = (0, exports.skipCborItem)(buf, c);
+    return c;
+};
+exports.skipCborItem = skipCborItem;
+/** Byte span of the witness set (element 1) inside `transaction = [body, witness_set, is_valid, aux]`. */
+const locateWitnessSet = (txBytes) => {
+    const outer = (0, exports.readCborHeader)(txBytes, 0);
+    if (outer.majorType !== 4)
+        throw new Error('Transaction CBOR is not an array');
+    const start = (0, exports.skipCborItem)(txBytes, outer.headerEnd);
+    return { start, end: (0, exports.skipCborItem)(txBytes, start) };
+};
+exports.locateWitnessSet = locateWitnessSet;
+/** Byte span of the transaction body (element 0). The tx id is blake2b-256 over exactly these bytes. */
+const locateTxBody = (txBytes) => {
+    const outer = (0, exports.readCborHeader)(txBytes, 0);
+    if (outer.majorType !== 4)
+        throw new Error('Transaction CBOR is not an array');
+    return { start: outer.headerEnd, end: (0, exports.skipCborItem)(txBytes, outer.headerEnd) };
+};
+exports.locateTxBody = locateTxBody;
+const encodeUintHeader = (majorType, value) => {
+    const tag = majorType << 5;
+    if (value < 24)
+        return Buffer.from([tag | value]);
+    if (value < 0x100)
+        return Buffer.from([tag | 24, value]);
+    if (value < 0x10000)
+        return Buffer.from([tag | 25, (value >> 8) & 0xff, value & 0xff]);
+    return Buffer.from([tag | 26, (value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff]);
+};
+const parseMapEntries = (buf, mapStart) => {
+    const hdr = (0, exports.readCborHeader)(buf, mapStart);
+    if (hdr.majorType !== 5)
+        throw new Error('Expected CBOR map for witness set');
+    if (hdr.additionalInfo === 31)
+        throw new Error('Indefinite-length witness-set map not supported');
+    const entries = [];
+    let off = hdr.headerEnd;
+    for (let i = 0; i < hdr.length; i++) {
+        const keyEnd = (0, exports.skipCborItem)(buf, off);
+        const valueEnd = (0, exports.skipCborItem)(buf, keyEnd);
+        entries.push({ keyStart: off, keyEnd, valueStart: keyEnd, valueEnd });
+        off = valueEnd;
+    }
+    return entries;
+};
+const findUintKey = (entries, buf, key) => entries.find((e) => {
+    const hdr = (0, exports.readCborHeader)(buf, e.keyStart);
+    return hdr.majorType === 0 && hdr.length === key && hdr.headerEnd === e.keyEnd;
+});
+// `tag(258, array)` (Conway set) or a bare array → element count + raw element bytes.
+const splitVkeyArray = (buf, valueStart, valueEnd) => {
+    let off = valueStart;
+    const first = (0, exports.readCborHeader)(buf, off);
+    if (first.majorType === 6 && first.length === 258)
+        off = first.headerEnd;
+    const arr = (0, exports.readCborHeader)(buf, off);
+    if (arr.majorType !== 4)
+        throw new Error('Expected vkey-witness array');
+    if (arr.additionalInfo === 31)
+        throw new Error('Indefinite-length vkey-witness array not supported');
+    return { count: arr.length, itemsBytes: Buffer.from(buf.slice(arr.headerEnd, valueEnd)) };
+};
+// Backends size fees with placeholder vkeys whose pubkeys are (almost) all zero. Those must be
+// replaced by real signatures, never kept alongside them. A real ed25519 pubkey never begins with
+// 28+ zero bytes.
+const dropPlaceholderVkeys = (itemsBytes, count) => {
+    const kept = [];
+    let off = 0;
+    for (let i = 0; i < count; i++) {
+        const itemStart = off;
+        const arr = (0, exports.readCborHeader)(itemsBytes, off);
+        const pub = (0, exports.readCborHeader)(itemsBytes, arr.headerEnd);
+        const pubBytes = itemsBytes.subarray(pub.headerEnd, pub.headerEnd + pub.length);
+        off = (0, exports.skipCborItem)(itemsBytes, (0, exports.skipCborItem)(itemsBytes, arr.headerEnd));
+        let leadingZeros = 0;
+        for (const b of pubBytes) {
+            if (b !== 0)
+                break;
+            leadingZeros++;
+        }
+        if (leadingZeros < 28)
+            kept.push(itemsBytes.subarray(itemStart, off));
+    }
+    return { itemsBytes: Buffer.concat(kept), count: kept.length };
+};
+/**
+ * Merge a CIP-30 `signTx(tx, partialSign=true)` witness set into the unsigned tx WITHOUT
+ * re-encoding the body or any non-vkey witness entry (scripts, redeemers, datums stay
+ * byte-identical). Existing real vkey witnesses (e.g. a backend policy pre-sign) are preserved;
+ * fee-estimation placeholders are dropped.
+ */
+const mergeWitnessSet = (unsignedTxHex, walletWitnessSetHex) => {
+    const txBytes = Buffer.from(unsignedTxHex, 'hex');
+    const walletBytes = Buffer.from(walletWitnessSetHex, 'hex');
+    const { start: wsStart, end: wsEnd } = (0, exports.locateWitnessSet)(txBytes);
+    const existing = parseMapEntries(txBytes, wsStart);
+    const wallet = parseMapEntries(walletBytes, 0);
+    const existingVkey = findUintKey(existing, txBytes, 0);
+    const walletVkey = findUintKey(wallet, walletBytes, 0);
+    if (!walletVkey)
+        return unsignedTxHex;
+    let mergedVkeyValue;
+    if (existingVkey) {
+        const ours = splitVkeyArray(txBytes, existingVkey.valueStart, existingVkey.valueEnd);
+        const kept = dropPlaceholderVkeys(ours.itemsBytes, ours.count);
+        const theirs = splitVkeyArray(walletBytes, walletVkey.valueStart, walletVkey.valueEnd);
+        mergedVkeyValue = Buffer.concat([
+            Buffer.from([0xd9, 0x01, 0x02]),
+            encodeUintHeader(4, kept.count + theirs.count),
+            kept.itemsBytes,
+            theirs.itemsBytes
+        ]);
+    }
+    else {
+        mergedVkeyValue = Buffer.from(walletBytes.subarray(walletVkey.valueStart, walletVkey.valueEnd));
+    }
+    // Key 0 first keeps the witness map canonical; every other entry is copied byte-for-byte.
+    const others = existing.filter((e) => e !== existingVkey);
+    const newWitnessSet = Buffer.concat([
+        encodeUintHeader(5, others.length + 1),
+        Buffer.from([0x00]),
+        mergedVkeyValue,
+        ...others.map((e) => txBytes.subarray(e.keyStart, e.valueEnd))
+    ]);
+    return Buffer.concat([txBytes.subarray(0, wsStart), newWitnessSet, txBytes.subarray(wsEnd)]).toString('hex');
+};
+exports.mergeWitnessSet = mergeWitnessSet;
+const compareEncodedKeys = (a, b) => (a.length !== b.length ? a.length - b.length : Buffer.compare(a, b));
+/**
+ * Canonical-CBOR check (CIP-21 key order) for the transaction-structure maps only: the body map
+ * (tx[0]) and the witness map (tx[1]). Hardware wallets and Eternl reject a tx whose structure maps
+ * are out of canonical order. Plutus data and multi-asset maps are deliberately NOT checked — they
+ * are hashed as-is and canonicalizing them would change hashes.
+ */
+const findCanonicalCborViolations = (txHex) => {
+    const b = Buffer.from(txHex, 'hex');
+    const violations = [];
+    const walk = (p, path, checkMapKeys) => {
+        const { majorType, additionalInfo, length, headerEnd } = (0, exports.readCborHeader)(b, p);
+        const indefinite = additionalInfo === 31;
+        let q = headerEnd;
+        switch (majorType) {
+            case 0:
+            case 1:
+            case 7:
+                return q;
+            case 2:
+            case 3:
+                if (indefinite) {
+                    while (b[q] !== 0xff)
+                        q = walk(q, path, false);
+                    return q + 1;
+                }
+                return q + length;
+            case 4: {
+                let i = 0;
+                while (indefinite ? b[q] !== 0xff : i < length)
+                    q = walk(q, `${path}[${i++}]`, false);
+                return indefinite ? q + 1 : q;
+            }
+            case 5: {
+                if (indefinite && checkMapKeys)
+                    violations.push({ path, detail: 'indefinite-length transaction map' });
+                let prevKey = null;
+                for (let i = 0; indefinite ? b[q] !== 0xff : i < length; i++) {
+                    const keyStart = q;
+                    q = walk(q, `${path}{k${i}}`, false);
+                    if (checkMapKeys) {
+                        const keyBytes = Buffer.from(b.subarray(keyStart, q));
+                        if (prevKey && compareEncodedKeys(prevKey, keyBytes) > 0) {
+                            violations.push({
+                                path,
+                                detail: `key #${i} (0x${keyBytes.toString('hex')}) out of canonical order (follows 0x${prevKey.toString('hex')})`
+                            });
+                        }
+                        prevKey = keyBytes;
+                    }
+                    q = walk(q, `${path}{v${i}}`, false);
+                }
+                return indefinite ? q + 1 : q;
+            }
+            case 6:
+                return walk(q, `${path}/tag(${length})`, false);
+            default:
+                throw new Error(`bad major type ${majorType} at byte ${p}`);
+        }
+    };
+    try {
+        const outer = (0, exports.readCborHeader)(b, 0);
+        if (outer.majorType !== 4)
+            throw new Error('transaction is not a CBOR array');
+        let q = outer.headerEnd;
+        for (let i = 0; i < outer.length && q < b.length; i++)
+            q = walk(q, `tx[${i}]`, i === 0 || i === 1);
+    }
+    catch (e) {
+        violations.push({ path: 'tx', detail: `parse error: ${e.message}` });
+    }
+    return violations;
+};
+exports.findCanonicalCborViolations = findCanonicalCborViolations;
+const assertCanonicalCbor = (txHex, label = 'tx') => {
+    const violations = (0, exports.findCanonicalCborViolations)(txHex);
+    if (violations.length > 0) {
+        const lines = violations
+            .slice(0, 12)
+            .map((v) => `  - ${v.path}: ${v.detail}`)
+            .join('\n');
+        throw new Error(`CBOR is not canonical (${label}) — a hardware wallet / Eternl would reject this tx at signing:\n${lines}`);
+    }
+};
+exports.assertCanonicalCbor = assertCanonicalCbor;

package/tx/index.d.ts

@@ -0,0 +1,4 @@
+export * from './cbor';
+/** Transaction id = blake2b-256 over the exact body bytes. Use it to prove the tx that was
+ *  signed/submitted is byte-for-byte the tx the backend built. */
+export declare const txHashFromCbor: (txHex: string) => string;

package/tx/index.js

@@ -0,0 +1,29 @@
+"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.txHashFromCbor = void 0;
+// Subpath module: `@koralabs/kora-labs-common/tx`. Isomorphic (browser + Node), no network.
+const blakejs_1 = require("blakejs");
+const cbor_1 = require("./cbor");
+__exportStar(require("./cbor"), exports);
+/** Transaction id = blake2b-256 over the exact body bytes. Use it to prove the tx that was
+ *  signed/submitted is byte-for-byte the tx the backend built. */
+const txHashFromCbor = (txHex) => {
+    const bytes = Buffer.from(txHex, 'hex');
+    const { start, end } = (0, cbor_1.locateTxBody)(bytes);
+    return (0, blakejs_1.blake2bHex)(bytes.subarray(start, end), undefined, 32);
+};
+exports.txHashFromCbor = txHashFromCbor;