tbc-tx-parser 0.1.0

package/dist/result/semantic.js

@@ -0,0 +1,950 @@
+import { buildOrderBookFacts, matchOrderBookAction } from '../protocols/order-book/index.js';
+// Convert verified movements and orders into human-readable semantics without scanning raw script markers.
+const NATIVE_TBC_ASSET = { type: 'native', symbol: 'TBC' };
+function uniqueSemanticParties(parties) {
+    // Actors may come from multiple effects or relations; deduplicate by role and owner for stable UI output.
+    const seen = new Set();
+    const unique = [];
+    for (const party of parties) {
+        if (!party) {
+            continue;
+        }
+        const key = `${party.role}:${party.address ?? ''}:${party.hash ?? ''}:${party.inputIndex ?? ''}:${party.outputIndex ?? ''}:${party.label ?? ''}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(party);
+    }
+    return unique;
+}
+function uniqueNumbers(values) {
+    return [...new Set(values.filter((value) => value !== undefined && value >= 0))];
+}
+function firstInputAddress(inputs) {
+    return inputs.map((input) => input.prevout?.address).find((address) => Boolean(address));
+}
+function tokenAssetFromMovement(movement) {
+    return {
+        type: movement.isStableCoin ? 'stablecoin' : 'ft',
+        symbol: movement.symbol,
+        name: movement.name,
+        contractId: movement.contractId,
+        decimal: movement.decimal,
+    };
+}
+function nftAssetFromMovement(movement) {
+    if (movement.action === 'mintCollection') {
+        return {
+            type: 'nftCollection',
+            name: movement.collectionName,
+            collectionId: movement.collectionId,
+            contractId: movement.contractId,
+        };
+    }
+    return {
+        type: 'nft',
+        symbol: movement.symbol,
+        name: movement.nftName ?? movement.collectionName,
+        collectionId: movement.collectionId,
+        contractId: movement.contractId,
+    };
+}
+function poolNftTokenAsset(movement) {
+    return {
+        type: 'ft',
+        symbol: movement.ftSymbol ?? 'FT',
+        name: movement.ftName,
+        contractId: movement.ftTokenId ?? movement.ftContractTxid,
+        decimal: movement.ftDecimal,
+    };
+}
+function poolNftLpAsset(movement) {
+    return {
+        type: 'ft',
+        symbol: movement.ftSymbol ? `${movement.ftSymbol}-LP` : 'LP',
+        name: movement.ftName ? `${movement.ftName} LP` : undefined,
+        contractId: movement.lpTokenId,
+        decimal: movement.ftDecimal,
+    };
+}
+function poolNftCreateAsset(movement) {
+    if (movement.action !== 'create' || !movement.contractId) {
+        return undefined;
+    }
+    return {
+        type: 'nft',
+        subtype: 'poolNft',
+        contractId: movement.contractId,
+        poolNft: {
+            version: movement.version ?? 1,
+            ...(movement.serviceFeeRate !== undefined ? { serviceFeeRate: movement.serviceFeeRate } : {}),
+            ...(movement.lpPlan !== undefined ? { lpPlan: movement.lpPlan } : {}),
+            ...(movement.withLock !== undefined ? { withLock: movement.withLock } : {}),
+            ...(movement.withLockTime !== undefined ? { withLockTime: movement.withLockTime } : {}),
+        },
+    };
+}
+function ownerParty(role, owner) {
+    // An owner may be an address, hash, or label; never present a hash as an address.
+    if (!owner.address && !owner.hash && !owner.label) {
+        return undefined;
+    }
+    return {
+        role,
+        address: owner.address,
+        hash: owner.hash,
+        inputIndex: owner.inputIndex,
+        outputIndex: owner.outputIndex,
+        label: owner.label,
+    };
+}
+function poolNftPoolParty(movement) {
+    return {
+        role: 'pool',
+        address: movement.poolStateAddress,
+        hash: movement.poolStateAddress ? undefined : movement.poolStateHash,
+        label: movement.poolId ?? movement.ftContractTxid ?? 'PoolNFT pool',
+        outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+    };
+}
+function poolNftReceiverParty(movement) {
+    return ownerParty('receiver', {
+        address: movement.receiver,
+        hash: movement.receiverHash,
+        label: movement.receiver || movement.receiverHash ? undefined : 'PoolNFT user',
+    });
+}
+function poolNftSenderParty(movement) {
+    if (movement.action === 'mergeFtInPool') {
+        return poolNftPoolParty(movement);
+    }
+    return ownerParty('sender', {
+        address: movement.sender,
+        hash: movement.senderHash,
+    });
+}
+function poolNftFeeCollectorParty(feeOutput) {
+    return ownerParty('feeCollector', {
+        address: feeOutput.address,
+        outputIndex: feeOutput.outputIndex,
+        label: feeOutput.address ? undefined : 'PoolNFT fee collector',
+    });
+}
+function poolNftRawAmount(rawAmount, decimal) {
+    if (!rawAmount) {
+        return undefined;
+    }
+    return {
+        rawAmount,
+        decimal,
+    };
+}
+function buildTbcSemantic(transactionType, inputs, outputs) {
+    // TBC semantics cover ordinary transfers; the asset-flow layer adds TBC flows carried by protocol transactions.
+    if (transactionType !== 'TBC transfer') {
+        return undefined;
+    }
+    const sourceAddress = firstInputAddress(inputs);
+    const spendableOutputs = outputs.filter((output) => output.satoshis > 0 && output.scriptKind === 'p2pkh');
+    if (!spendableOutputs.length) {
+        return undefined;
+    }
+    const effects = spendableOutputs.map((output) => ({
+        kind: 'transfer',
+        asset: NATIVE_TBC_ASSET,
+        amount: { satoshis: output.satoshis },
+        from: sourceAddress ? { role: 'sender', address: sourceAddress } : { role: 'unknown' },
+        to: { role: 'receiver', address: output.address, outputIndex: output.index },
+        outputIndex: output.index,
+        source: 'decoded',
+    }));
+    return {
+        type: transactionType,
+        confidence: sourceAddress ? 'heuristic' : 'partial',
+        actors: uniqueSemanticParties([
+            sourceAddress ? { role: 'sender', address: sourceAddress } : undefined,
+            ...spendableOutputs.map((output) => ({ role: 'receiver', address: output.address, outputIndex: output.index })),
+        ]),
+        effects,
+        relations: [
+            {
+                kind: 'nativeTransfer',
+                confidence: sourceAddress ? 'heuristic' : 'partial',
+                inputIndexes: inputs.map((input) => input.index),
+                outputIndexes: spendableOutputs.map((output) => output.index),
+            },
+        ],
+        ...(sourceAddress ? {} : { notes: ['Input prevouts are required to identify the native TBC sender.'] }),
+    };
+}
+function buildCoinbaseSemantic(transactionType, inputs, outputs) {
+    if (transactionType !== 'TBC coinbase') {
+        return undefined;
+    }
+    const rewardOutputs = outputs.filter((output) => output.satoshis > 0);
+    const effects = rewardOutputs.map((output) => ({
+        kind: 'mint',
+        asset: NATIVE_TBC_ASSET,
+        amount: { satoshis: output.satoshis },
+        to: {
+            role: 'miner',
+            address: output.address,
+            hash: output.address ? undefined : output.script.hex,
+            outputIndex: output.index,
+        },
+        outputIndex: output.index,
+        source: 'decoded',
+    }));
+    return {
+        type: transactionType,
+        confidence: 'exact',
+        actors: uniqueSemanticParties(rewardOutputs.map((output) => ({
+            role: 'miner',
+            address: output.address,
+            hash: output.address ? undefined : output.script.hex,
+            outputIndex: output.index,
+        }))),
+        effects,
+        relations: [
+            {
+                kind: 'nativeCoinbase',
+                confidence: 'exact',
+                inputIndexes: inputs.map((input) => input.index),
+                outputIndexes: rewardOutputs.map((output) => output.index),
+            },
+        ],
+        notes: ['Coinbase transaction creates block reward outputs and has no spendable input prevout.'],
+    };
+}
+function buildFtSemantic(transactionType, inputs, outputs, movements) {
+    // FT semantics reuse movement asset data and infer an input owner only for assets that already existed.
+    if (!movements.length) {
+        return undefined;
+    }
+    const sourceAddress = firstInputAddress(inputs);
+    const isMintTransaction = transactionType.endsWith('mint');
+    const effects = movements.map((movement, movementIndex) => {
+        const isMint = movementIndex === 0 && isMintTransaction;
+        const from = isMint
+            ? undefined
+            : sourceAddress
+                ? { role: 'sender', address: sourceAddress }
+                : { role: 'unknown' };
+        return {
+            kind: isMint ? 'mint' : 'transfer',
+            asset: tokenAssetFromMovement(movement),
+            amount: {
+                rawAmount: movement.rawAmount,
+                displayAmount: movement.displayAmount,
+                decimal: movement.decimal,
+            },
+            ...(from ? { from } : {}),
+            to: { role: 'receiver', address: movement.receiver, outputIndex: movement.outputIndex },
+            outputIndex: movement.outputIndex,
+            tapeOutputIndex: movement.tapeOutputIndex,
+            movementIndex,
+            source: 'decoded',
+        };
+    });
+    const relationKind = movements.some((movement) => movement.isStableCoin) ? 'stablecoinTransfer' : 'ftTransfer';
+    return {
+        type: transactionType,
+        confidence: sourceAddress ? 'heuristic' : 'partial',
+        actors: uniqueSemanticParties([
+            !isMintTransaction && sourceAddress ? { role: 'sender', address: sourceAddress } : undefined,
+            ...movements.map((movement) => ({ role: 'receiver', address: movement.receiver, outputIndex: movement.outputIndex })),
+        ]),
+        effects,
+        relations: [
+            {
+                kind: relationKind,
+                confidence: sourceAddress ? 'heuristic' : 'partial',
+                inputIndexes: inputs.map((input) => input.index),
+                outputIndexes: movements.flatMap((movement) => [movement.outputIndex, movement.tapeOutputIndex]),
+                movementIndexes: movements.map((_movement, index) => index),
+            },
+        ],
+        ...(sourceAddress || isMintTransaction ? {} : { notes: ['Input prevouts are required to identify the token sender.'] }),
+    };
+}
+function buildNftSemantic(transactionType, movements) {
+    // NFT semantics are built only from verified movements.
+    if (!movements.length) {
+        return undefined;
+    }
+    const effects = movements.map((movement, movementIndex) => {
+        if (movement.action === 'mintCollection') {
+            const to = ownerParty('receiver', { address: movement.mintSlotAddress });
+            return {
+                kind: 'mint',
+                asset: nftAssetFromMovement(movement),
+                amount: {
+                    rawAmount: '1',
+                    displayAmount: '1',
+                    decimal: 0,
+                },
+                ...(to ? { to } : {}),
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'decoded',
+            };
+        }
+        const from = movement.action === 'transfer' || movement.action === 'burn'
+            ? ownerParty('sender', { address: movement.sender })
+            : undefined;
+        const to = movement.action === 'burn'
+            ? undefined
+            : ownerParty('receiver', {
+                address: movement.receiver,
+                outputIndex: movement.holdOutputIndex ?? movement.outputIndex,
+            });
+        return {
+            kind: movement.action,
+            asset: nftAssetFromMovement(movement),
+            amount: {
+                rawAmount: '1',
+                displayAmount: '1',
+                decimal: 0,
+            },
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+            outputIndex: movement.outputIndex ?? movement.holdOutputIndex,
+            tapeOutputIndex: movement.tapeOutputIndex,
+            movementIndex,
+            source: 'decoded',
+        };
+    });
+    const relationKind = movements[0]?.action === 'mintCollection'
+        ? 'nftCollectionMint'
+        : movements[0]?.action === 'mint'
+            ? 'nftMint'
+            : movements[0]?.action === 'burn'
+                ? 'nftBurn'
+                : 'nftTransfer';
+    const hasPartialOwner = movements.some((movement) => (movement.action === 'transfer' && !movement.sender) ||
+        ((movement.action === 'mint' || movement.action === 'transfer') && !movement.receiver));
+    return {
+        type: transactionType,
+        confidence: hasPartialOwner ? 'partial' : 'exact',
+        actors: uniqueSemanticParties([
+            ...movements.map((movement) => movement.action === 'transfer' || movement.action === 'burn'
+                ? ownerParty('sender', { address: movement.sender })
+                : undefined),
+            ...movements.map((movement) => movement.action === 'burn'
+                ? undefined
+                : ownerParty('receiver', {
+                    address: movement.receiver,
+                    outputIndex: movement.holdOutputIndex ?? movement.outputIndex,
+                })),
+            ...movements.map((movement) => movement.action === 'mintCollection'
+                ? ownerParty('creator', { label: movement.collectionName, outputIndex: movement.tapeOutputIndex })
+                : undefined),
+        ]),
+        effects,
+        relations: [
+            {
+                kind: relationKind,
+                confidence: hasPartialOwner ? 'partial' : 'exact',
+                outputIndexes: movements
+                    .flatMap((movement) => [movement.outputIndex, movement.holdOutputIndex, movement.tapeOutputIndex])
+                    .filter((index) => index !== undefined),
+                movementIndexes: movements.map((_movement, index) => index),
+            },
+        ],
+    };
+}
+function buildPoolNftSemantic(transactionType, movements) {
+    if (!movements.length) {
+        return undefined;
+    }
+    const effects = movements.flatMap((movement, movementIndex) => {
+        const pool = poolNftPoolParty(movement);
+        const receiver = poolNftReceiverParty(movement);
+        const sender = poolNftSenderParty(movement);
+        const userIn = sender ?? receiver;
+        const userOut = receiver ?? sender;
+        const tokenAsset = poolNftTokenAsset(movement);
+        const lpAsset = poolNftLpAsset(movement);
+        const movementEffects = [];
+        const createAsset = poolNftCreateAsset(movement);
+        if (createAsset) {
+            movementEffects.push({
+                kind: 'mint',
+                asset: createAsset,
+                amount: { rawAmount: '1', displayAmount: '1', decimal: 0 },
+                to: pool,
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'decoded',
+            });
+        }
+        if (movement.stateTbcSatoshis !== undefined || movement.tbcSatoshis !== undefined) {
+            movementEffects.push({
+                kind: 'state',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: movement.stateTbcSatoshis ?? movement.tbcSatoshis },
+                to: pool,
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'decoded',
+            });
+        }
+        if (movement.tbcInSatoshis !== undefined && movement.tbcInSatoshis > 0) {
+            movementEffects.push({
+                kind: 'transfer',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: movement.tbcInSatoshis },
+                ...(userIn ? { from: userIn } : {}),
+                to: pool,
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        if (movement.tbcOutSatoshis !== undefined && movement.tbcOutSatoshis > 0) {
+            movementEffects.push({
+                kind: 'transfer',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: movement.tbcOutSatoshis },
+                from: pool,
+                ...(userOut ? { to: userOut } : {}),
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        const ftInAmount = poolNftRawAmount(movement.ftInRawAmount, movement.ftDecimal);
+        if (ftInAmount) {
+            movementEffects.push({
+                kind: movement.action === 'mergeFtInPool' ? 'self' : 'transfer',
+                asset: tokenAsset,
+                amount: ftInAmount,
+                ...(userIn ? { from: userIn } : {}),
+                to: pool,
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        const ftOutAmount = poolNftRawAmount(movement.ftOutRawAmount, movement.ftDecimal);
+        if (ftOutAmount) {
+            movementEffects.push({
+                kind: 'transfer',
+                asset: tokenAsset,
+                amount: ftOutAmount,
+                from: pool,
+                ...(userOut ? { to: userOut } : {}),
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        const ftLpInAmount = poolNftRawAmount(movement.ftLpInRawAmount, movement.ftDecimal);
+        if (ftLpInAmount) {
+            movementEffects.push({
+                kind: 'burn',
+                asset: lpAsset,
+                amount: ftLpInAmount,
+                ...(userIn ? { from: userIn } : {}),
+                to: {
+                    role: 'burn',
+                    ...(movement.action === 'burnFtLp' ? { address: movement.receiver } : { label: 'PoolNFT burn' }),
+                },
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'decoded',
+            });
+        }
+        const ftLpOutAmount = poolNftRawAmount(movement.ftLpOutRawAmount, movement.ftDecimal);
+        if (ftLpOutAmount) {
+            movementEffects.push({
+                kind: 'mint',
+                asset: lpAsset,
+                amount: ftLpOutAmount,
+                ...(userOut ? { to: userOut } : {}),
+                outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        for (const feeOutput of movement.feeOutputs ?? []) {
+            const feeCollector = poolNftFeeCollectorParty(feeOutput);
+            movementEffects.push({
+                kind: 'fee',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: feeOutput.satoshis },
+                ...(userIn ? { from: userIn } : {}),
+                ...(feeCollector ? { to: feeCollector } : {}),
+                outputIndex: feeOutput.outputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+                movementIndex,
+                source: 'derived',
+            });
+        }
+        return movementEffects;
+    });
+    const hasHeuristic = movements.some((movement) => movement.confidence === 'heuristic');
+    return {
+        type: transactionType,
+        confidence: hasHeuristic ? 'heuristic' : 'exact',
+        actors: uniqueSemanticParties([
+            ...movements.map(poolNftPoolParty),
+            ...movements.map(poolNftSenderParty),
+            ...movements.map(poolNftReceiverParty),
+            ...movements.flatMap((movement) => (movement.feeOutputs ?? []).map(poolNftFeeCollectorParty)),
+            ...movements
+                .filter((movement) => movement.ftLpInRawAmount)
+                .map((movement) => ownerParty('burn', movement.action === 'burnFtLp' ? { address: movement.receiver } : { label: 'PoolNFT burn' })),
+        ]),
+        effects,
+        relations: [
+            {
+                kind: 'poolNftAction',
+                confidence: hasHeuristic ? 'heuristic' : 'exact',
+                inputIndexes: movements.map((movement) => movement.poolStateInputIndex).filter((index) => index !== undefined),
+                outputIndexes: movements
+                    .flatMap((movement) => [movement.poolStateOutputIndex, movement.poolOutputIndex, movement.tapeOutputIndex])
+                    .filter((index) => index !== undefined),
+                movementIndexes: movements.map((_movement, index) => index),
+            },
+        ],
+        notes: movements.flatMap((movement) => movement.reasons ?? []),
+    };
+}
+function buildOrderBookSemantic(transactionType, orderBookOrders, ftMovements, outputs) {
+    // OrderBook semantics consume protocol facts and matcher results; settlement centralizes amount formulas and output matching.
+    if (!orderBookOrders.length) {
+        return undefined;
+    }
+    const facts = buildOrderBookFacts(orderBookOrders, ftMovements, outputs);
+    const match = matchOrderBookAction(facts);
+    const inputOrders = match?.inputOrders ?? facts.inputOrders;
+    const outputOrders = match?.outputOrders ?? facts.outputOrders;
+    const actors = facts.orders.map((order) => ({
+        role: order.side === 'buy' ? 'buyer' : 'seller',
+        address: order.holdAddress,
+        inputIndex: order.inputIndex,
+        outputIndex: order.outputIndex,
+    }));
+    if (match?.action === 'match' && match.buyOrder && match.sellOrder && match.settlement) {
+        const { buyOrder, sellOrder, settlement } = match;
+        const { buyerTbcSatoshis, tbcFeeSatoshis, sellerFtRaw, ftFeeRaw, buyerTbcOutput, tbcFeeOutput, sellerFtMovement, ftFeeMovement, tokenTemplate, matchedSatoshis, remainders, } = settlement;
+        const tokenAsset = tokenTemplate ? tokenAssetFromMovement(tokenTemplate) : undefined;
+        const effects = [];
+        const completeRemainders = remainders.filter((remainder) => remainder.isComplete);
+        const settlementMovements = [
+            sellerFtMovement,
+            ftFeeMovement,
+            ...completeRemainders.map((remainder) => remainder.ftMovement),
+        ].filter((movement) => Boolean(movement));
+        if (buyerTbcOutput) {
+            effects.push({
+                kind: 'transfer',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: buyerTbcSatoshis },
+                from: { role: 'seller', address: sellOrder.holdAddress, inputIndex: sellOrder.inputIndex },
+                to: { role: 'buyer', address: buyOrder.holdAddress, outputIndex: buyerTbcOutput.index },
+                inputIndex: sellOrder.inputIndex,
+                outputIndex: buyerTbcOutput.index,
+                source: 'derived',
+            });
+        }
+        if (tokenAsset && sellerFtMovement) {
+            effects.push({
+                kind: 'transfer',
+                asset: tokenAsset,
+                amount: {
+                    rawAmount: sellerFtRaw,
+                    displayAmount: sellerFtMovement.displayAmount,
+                    decimal: sellerFtMovement.decimal,
+                },
+                from: { role: 'buyer', address: buyOrder.holdAddress, inputIndex: buyOrder.inputIndex },
+                to: { role: 'seller', address: sellOrder.holdAddress, outputIndex: sellerFtMovement.outputIndex },
+                inputIndex: buyOrder.inputIndex,
+                outputIndex: sellerFtMovement.outputIndex,
+                tapeOutputIndex: sellerFtMovement.tapeOutputIndex,
+                movementIndex: ftMovements.indexOf(sellerFtMovement),
+                source: 'derived',
+            });
+        }
+        if (tbcFeeSatoshis > 0 && tbcFeeOutput) {
+            effects.push({
+                kind: 'fee',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: tbcFeeSatoshis },
+                from: { role: 'seller', address: sellOrder.holdAddress, inputIndex: sellOrder.inputIndex },
+                to: { role: 'feeCollector', address: tbcFeeOutput.address, outputIndex: tbcFeeOutput.index },
+                inputIndex: sellOrder.inputIndex,
+                outputIndex: tbcFeeOutput.index,
+                source: 'derived',
+            });
+        }
+        if (tokenAsset && BigInt(ftFeeRaw) > 0n && ftFeeMovement) {
+            effects.push({
+                kind: 'fee',
+                asset: tokenAsset,
+                amount: {
+                    rawAmount: ftFeeRaw,
+                    displayAmount: ftFeeMovement.displayAmount,
+                    decimal: ftFeeMovement.decimal,
+                },
+                from: { role: 'buyer', address: buyOrder.holdAddress, inputIndex: buyOrder.inputIndex },
+                to: { role: 'feeCollector', address: ftFeeMovement.receiver, outputIndex: ftFeeMovement.outputIndex },
+                inputIndex: buyOrder.inputIndex,
+                outputIndex: ftFeeMovement.outputIndex,
+                tapeOutputIndex: ftFeeMovement.tapeOutputIndex,
+                movementIndex: ftMovements.indexOf(ftFeeMovement),
+                source: 'derived',
+            });
+        }
+        for (const remainder of completeRemainders) {
+            if (!remainder.outputOrder || remainder.outputOrder.satoshis === undefined) {
+                continue;
+            }
+            effects.push({
+                kind: 'state',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: remainder.outputOrder.satoshis },
+                to: {
+                    role: remainder.outputOrder.side === 'buy' ? 'buyer' : 'seller',
+                    address: remainder.outputOrder.holdAddress,
+                    outputIndex: remainder.outputOrder.outputIndex,
+                },
+                inputIndex: remainder.inputOrder.inputIndex,
+                outputIndex: remainder.outputOrder.outputIndex,
+                movementIndex: remainder.outputOrder.orderIndex,
+                source: 'decoded',
+            });
+        }
+        return {
+            type: transactionType,
+            confidence: match.confidence,
+            actors: uniqueSemanticParties([
+                ...actors,
+                tbcFeeOutput ? { role: 'feeCollector', address: tbcFeeOutput.address, outputIndex: tbcFeeOutput.index } : undefined,
+                ftFeeMovement ? { role: 'feeCollector', address: ftFeeMovement.receiver, outputIndex: ftFeeMovement.outputIndex } : undefined,
+            ]),
+            effects,
+            relations: [
+                {
+                    kind: 'orderBookMatch',
+                    confidence: match.confidence,
+                    inputIndexes: inputOrders.map((order) => order.inputIndex).filter((index) => index !== undefined),
+                    outputIndexes: [
+                        buyerTbcOutput?.index,
+                        tbcFeeOutput?.index,
+                        sellerFtMovement?.outputIndex,
+                        sellerFtMovement?.tapeOutputIndex,
+                        ftFeeMovement?.outputIndex,
+                        ftFeeMovement?.tapeOutputIndex,
+                        ...completeRemainders.map((remainder) => remainder.outputOrder?.outputIndex),
+                        ...completeRemainders.flatMap((remainder) => [
+                            remainder.ftMovement?.outputIndex,
+                            remainder.ftMovement?.tapeOutputIndex,
+                        ]),
+                    ].filter((index) => index !== undefined),
+                    movementIndexes: uniqueNumbers(settlementMovements.map((movement) => ftMovements.indexOf(movement))),
+                    orderIndexes: uniqueNumbers([
+                        buyOrder.orderIndex,
+                        sellOrder.orderIndex,
+                        ...completeRemainders.map((remainder) => remainder.outputOrder?.orderIndex),
+                    ]),
+                    buyOrderIndex: buyOrder.orderIndex,
+                    sellOrderIndex: sellOrder.orderIndex,
+                    remainingOrderIndexes: remainders
+                        .filter((remainder) => remainder.isComplete)
+                        .map((remainder) => remainder.outputOrder?.orderIndex)
+                        .filter((index) => index !== undefined),
+                    priceRaw: sellOrder.unitPriceRaw,
+                    matchedSatoshis,
+                },
+            ],
+            ...(match.reasons.length ? { notes: match.reasons } : {}),
+        };
+    }
+    if ((match?.action === 'cancelBuy' || match?.action === 'cancelSell') && match.cancelRelease) {
+        const { cancelRelease } = match;
+        const { order } = cancelRelease;
+        const effects = [];
+        if (cancelRelease.asset === 'tbc' && cancelRelease.tbcOutput) {
+            effects.push({
+                kind: 'orderRelease',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: cancelRelease.tbcOutput.satoshis },
+                to: {
+                    role: 'orderHolder',
+                    address: order.holdAddress,
+                    inputIndex: order.inputIndex,
+                    outputIndex: cancelRelease.tbcOutput.index,
+                },
+                inputIndex: order.inputIndex,
+                outputIndex: cancelRelease.tbcOutput.index,
+                movementIndex: order.orderIndex,
+                source: 'derived',
+            });
+        }
+        if (cancelRelease.asset === 'ft' && cancelRelease.ftMovement) {
+            effects.push({
+                kind: 'orderRelease',
+                asset: tokenAssetFromMovement(cancelRelease.ftMovement),
+                amount: {
+                    rawAmount: cancelRelease.ftMovement.rawAmount,
+                    displayAmount: cancelRelease.ftMovement.displayAmount,
+                    decimal: cancelRelease.ftMovement.decimal,
+                },
+                to: {
+                    role: 'orderHolder',
+                    address: order.holdAddress,
+                    outputIndex: cancelRelease.ftMovement.outputIndex,
+                },
+                inputIndex: order.inputIndex,
+                outputIndex: cancelRelease.ftMovement.outputIndex,
+                tapeOutputIndex: cancelRelease.ftMovement.tapeOutputIndex,
+                movementIndex: ftMovements.indexOf(cancelRelease.ftMovement),
+                source: 'derived',
+            });
+        }
+        return {
+            type: transactionType,
+            confidence: match.confidence,
+            actors: uniqueSemanticParties(actors),
+            effects,
+            relations: [
+                {
+                    kind: 'orderBookCancel',
+                    confidence: match.confidence,
+                    inputIndexes: inputOrders.map((inputOrder) => inputOrder.inputIndex).filter((index) => index !== undefined),
+                    outputIndexes: [
+                        cancelRelease.tbcOutput?.index,
+                        cancelRelease.ftMovement?.outputIndex,
+                        cancelRelease.ftMovement?.tapeOutputIndex,
+                    ].filter((index) => index !== undefined),
+                    movementIndexes: cancelRelease.ftMovement ? [ftMovements.indexOf(cancelRelease.ftMovement)] : [],
+                    orderIndexes: [order.orderIndex],
+                },
+            ],
+            ...(match.reasons.length ? { notes: match.reasons } : {}),
+        };
+    }
+    if (match?.action === 'update' && match.updateContinuity) {
+        const { updateContinuity } = match;
+        const { inputOrder, outputOrder } = updateContinuity;
+        const effects = [];
+        const updateStateIsComplete = updateContinuity.isContinuous &&
+            outputOrder &&
+            outputOrder.satoshis !== undefined &&
+            (!match.updateDelta ||
+                match.updateDelta.direction === 'none' ||
+                match.updateDelta.isComplete);
+        if (updateStateIsComplete) {
+            effects.push({
+                kind: 'state',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: outputOrder.satoshis },
+                to: {
+                    role: 'orderHolder',
+                    address: outputOrder.holdAddress,
+                    outputIndex: outputOrder.outputIndex,
+                },
+                inputIndex: inputOrder?.inputIndex,
+                outputIndex: outputOrder.outputIndex,
+                movementIndex: outputOrder.orderIndex,
+                source: 'decoded',
+            });
+        }
+        if (match.updateDelta?.isComplete && match.updateDelta.direction !== 'none') {
+            const { updateDelta } = match;
+            if (updateDelta.asset === 'ft' && updateDelta.ftMovement) {
+                effects.push({
+                    kind: updateDelta.direction === 'lock' ? 'orderLock' : 'orderRelease',
+                    asset: tokenAssetFromMovement(updateDelta.ftMovement),
+                    amount: {
+                        rawAmount: updateDelta.ftMovement.rawAmount,
+                        displayAmount: updateDelta.ftMovement.displayAmount,
+                        decimal: updateDelta.ftMovement.decimal,
+                    },
+                    to: {
+                        role: 'orderHolder',
+                        address: updateDelta.outputOrder.holdAddress,
+                        outputIndex: updateDelta.ftMovement.outputIndex,
+                    },
+                    inputIndex: updateDelta.inputOrder.inputIndex,
+                    outputIndex: updateDelta.ftMovement.outputIndex,
+                    tapeOutputIndex: updateDelta.ftMovement.tapeOutputIndex,
+                    movementIndex: ftMovements.indexOf(updateDelta.ftMovement),
+                    source: 'derived',
+                });
+            }
+            if (updateDelta.asset === 'tbc' && updateDelta.tbcOutput) {
+                effects.push({
+                    kind: updateDelta.direction === 'lock' ? 'orderLock' : 'orderRelease',
+                    asset: NATIVE_TBC_ASSET,
+                    amount: { satoshis: updateDelta.expectedSatoshis },
+                    to: {
+                        role: 'orderHolder',
+                        address: updateDelta.outputOrder.holdAddress,
+                        outputIndex: updateDelta.tbcOutput.index,
+                    },
+                    inputIndex: updateDelta.inputOrder.inputIndex,
+                    outputIndex: updateDelta.tbcOutput.index,
+                    movementIndex: updateDelta.outputOrder.orderIndex,
+                    source: 'derived',
+                });
+            }
+        }
+        return {
+            type: transactionType,
+            confidence: match.confidence,
+            actors: uniqueSemanticParties(actors),
+            effects,
+            relations: [
+                {
+                    kind: 'orderBookUpdate',
+                    confidence: match.confidence,
+                    inputIndexes: inputOrders.map((order) => order.inputIndex).filter((index) => index !== undefined),
+                    outputIndexes: outputOrders.map((order) => order.outputIndex).filter((index) => index !== undefined),
+                    orderIndexes: [inputOrder?.orderIndex, outputOrder?.orderIndex].filter((index) => index !== undefined),
+                    movementIndexes: match.updateDelta?.ftMovement ? [ftMovements.indexOf(match.updateDelta.ftMovement)] : [],
+                    oldOrderIndex: inputOrder?.orderIndex,
+                    newOrderIndex: outputOrder?.orderIndex,
+                    changedFields: updateContinuity.changedFields,
+                },
+            ],
+            ...(match.reasons.length ? { notes: match.reasons } : {}),
+        };
+    }
+    if ((match?.action === 'placeBuy' || match?.action === 'placeSell') && match.placeLock) {
+        const { placeLock } = match;
+        const { order } = placeLock;
+        const effects = [];
+        if (placeLock.asset === 'tbc' && placeLock.tbcOutput) {
+            effects.push({
+                kind: 'orderLock',
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: placeLock.tbcOutput.satoshis },
+                to: {
+                    role: 'orderHolder',
+                    address: order.holdAddress,
+                    outputIndex: placeLock.tbcOutput.index,
+                },
+                outputIndex: placeLock.tbcOutput.index,
+                movementIndex: order.orderIndex,
+                source: 'derived',
+            });
+        }
+        if (placeLock.asset === 'ft' && placeLock.ftMovement) {
+            effects.push({
+                kind: 'orderLock',
+                asset: tokenAssetFromMovement(placeLock.ftMovement),
+                amount: {
+                    rawAmount: placeLock.ftMovement.rawAmount,
+                    displayAmount: placeLock.ftMovement.displayAmount,
+                    decimal: placeLock.ftMovement.decimal,
+                },
+                to: {
+                    role: 'orderHolder',
+                    address: order.holdAddress,
+                    outputIndex: placeLock.ftMovement.outputIndex,
+                },
+                outputIndex: placeLock.ftMovement.outputIndex,
+                tapeOutputIndex: placeLock.ftMovement.tapeOutputIndex,
+                movementIndex: ftMovements.indexOf(placeLock.ftMovement),
+                source: 'derived',
+            });
+        }
+        return {
+            type: transactionType,
+            confidence: match.confidence,
+            actors: uniqueSemanticParties(actors),
+            effects,
+            relations: [
+                {
+                    kind: 'orderBookOrder',
+                    confidence: match.confidence,
+                    outputIndexes: [
+                        order.outputIndex,
+                        placeLock.tbcOutput?.index,
+                        placeLock.ftMovement?.outputIndex,
+                        placeLock.ftMovement?.tapeOutputIndex,
+                    ].filter((index) => index !== undefined),
+                    movementIndexes: placeLock.ftMovement ? [ftMovements.indexOf(placeLock.ftMovement)] : [],
+                    orderIndexes: [order.orderIndex],
+                },
+            ],
+            ...(match.reasons.length ? { notes: match.reasons } : {}),
+        };
+    }
+    const relationKind = match?.action === 'cancelBuy' || match?.action === 'cancelSell'
+        ? 'orderBookCancel'
+        : match?.action === 'update'
+            ? 'orderBookUpdate'
+            : 'orderBookOrder';
+    const effects = facts.orders.map((order) => ({
+        kind: order.source === 'output' ? 'orderLock' : 'orderRelease',
+        asset: NATIVE_TBC_ASSET,
+        amount: { satoshis: order.saleVolumeSatoshis },
+        to: { role: 'orderHolder', address: order.holdAddress, inputIndex: order.inputIndex, outputIndex: order.outputIndex },
+        inputIndex: order.inputIndex,
+        outputIndex: order.outputIndex,
+        movementIndex: order.orderIndex,
+        source: 'decoded',
+    }));
+    return {
+        type: transactionType,
+        confidence: match?.confidence ?? 'heuristic',
+        actors: uniqueSemanticParties(actors),
+        effects,
+        relations: [
+            {
+                kind: relationKind,
+                confidence: match?.confidence ?? 'heuristic',
+                inputIndexes: inputOrders.map((order) => order.inputIndex).filter((index) => index !== undefined),
+                outputIndexes: outputOrders.map((order) => order.outputIndex).filter((index) => index !== undefined),
+                orderIndexes: facts.orders.map((order) => order.orderIndex),
+            },
+        ],
+        ...(match?.reasons.length ? { notes: match.reasons } : {}),
+    };
+}
+export function buildSemantic(transactionType, inputs, outputs, ftMovements, nftMovements, orderBookOrders, poolNftMovements = []) {
+    // Apply semantic adapters by complexity: OrderBook consumes FT movements before NFT, FT, and TBC fallbacks.
+    return (buildOrderBookSemantic(transactionType, orderBookOrders, ftMovements, outputs) ??
+        buildPoolNftSemantic(transactionType, poolNftMovements) ??
+        buildNftSemantic(transactionType, nftMovements) ??
+        buildFtSemantic(transactionType, inputs, outputs, ftMovements) ??
+        buildCoinbaseSemantic(transactionType, inputs, outputs) ??
+        buildTbcSemantic(transactionType, inputs, outputs));
+}
+export function buildFallbackSemantic(transactionType, unsupported) {
+    // Return partial semantics when no adapter matches so callers know chain facts and asset flows remain available.
+    if (unsupported.length) {
+        return {
+            type: 'Unsupported contract',
+            confidence: 'partial',
+            actors: [],
+            effects: [],
+            relations: [],
+            notes: [
+                `Inferred transaction type before fallback: ${transactionType}.`,
+                'Contract script detected, but no supported protocol decoder matched it. Chain data is still available under chain.',
+            ],
+        };
+    }
+    return {
+        type: transactionType,
+        confidence: 'partial',
+        actors: [],
+        effects: [],
+        relations: [],
+        notes: ['No semantic adapter matched this transaction. Use chain data and assetFlows for protocol-specific UI.'],
+    };
+}
+//# sourceMappingURL=semantic.js.map