tbc-tx-parser 0.1.0

package/dist/result/index.js

@@ -0,0 +1,869 @@
+import { ScriptType, } from '../types.js';
+import { tbc } from '../adapters/tbc-lib.js';
+import { formatTokenRawAmount } from '../utils/token-amount.js';
+// Convert protocol movements, semantic effects, and native outputs into display-oriented asset flows.
+const NATIVE_TBC_ASSET = { type: 'tbc', symbol: 'TBC' };
+const MIN_NON_STANDARD_TBC_FLOW_SATOSHIS = 5_000;
+const FT_CODE_MARKER_HEX = '32436f6465';
+const FTLP_CODE_MARKER_HEX = '02436f6465';
+const ORDER_BOOK_ACTION_BY_TYPE = {
+    'OrderBook buy order': 'placeBuy',
+    'OrderBook sell order': 'placeSell',
+    'OrderBook buy order cancel': 'cancelBuy',
+    'OrderBook sell order cancel': 'cancelSell',
+    'OrderBook match': 'match',
+    'OrderBook order update': 'update',
+};
+function firstInputAddress(inputs) {
+    // Fallback source for ordinary TBC and legacy FT semantics; strict protocols should prefer verified movement sources.
+    return inputs.map((input) => input.prevout?.address).find((address) => Boolean(address));
+}
+function firstInputOwnerEndpoint(inputs) {
+    const input = inputs.find((item) => Boolean(item.prevout?.address ?? item.prevout?.hash));
+    if (!input?.prevout) {
+        return undefined;
+    }
+    return {
+        address: input.prevout.address,
+        hash: input.prevout.hash,
+    };
+}
+function scriptLockHash(scriptHex) {
+    if (!scriptHex || scriptHex.length % 2 !== 0) {
+        return undefined;
+    }
+    return tbc.crypto.Hash.sha256ripemd160(tbc.crypto.Hash.sha256(Buffer.from(scriptHex, 'hex'))).toString('hex');
+}
+function multiSigAddressByLockHash(inputs, outputs) {
+    // Some protocols expose only a lock hash; resolve it to an address when a matching MultiSig script is available.
+    const addressByHash = new Map();
+    for (const output of outputs) {
+        if (output.scriptKind !== 'multisig' || !output.address) {
+            continue;
+        }
+        const hash = scriptLockHash(output.script.hex);
+        if (hash) {
+            addressByHash.set(hash, output.address);
+        }
+    }
+    for (const input of inputs) {
+        const prevout = input.prevout;
+        if (prevout?.script.type !== ScriptType.MULTISIG || !prevout.address) {
+            continue;
+        }
+        const hash = scriptLockHash(prevout.script.hex);
+        if (hash) {
+            addressByHash.set(hash, prevout.address);
+        }
+    }
+    return addressByHash;
+}
+function isFtCodePrevout(input) {
+    const hex = input.prevout?.script.hex?.toLowerCase();
+    return Boolean(hex?.endsWith(FT_CODE_MARKER_HEX) || hex?.endsWith(FTLP_CODE_MARKER_HEX));
+}
+function ftInputOwnerEndpoint(inputs, outputs) {
+    // Prefer the verified FT Code prevout over the first ordinary input as the FT source.
+    const ftInput = inputs.find(isFtCodePrevout);
+    if (!ftInput?.prevout) {
+        return firstInputOwnerEndpoint(inputs);
+    }
+    const ownerHash = ftInput.prevout.hash ?? ftInput.prevout.script.data?.hash;
+    if (ownerHash) {
+        const address = multiSigAddressByLockHash(inputs, outputs).get(ownerHash);
+        return address ? { address } : { hash: ownerHash };
+    }
+    if (ftInput.prevout.address) {
+        return { address: ftInput.prevout.address };
+    }
+    return firstInputOwnerEndpoint(inputs);
+}
+function inputAddresses(inputs) {
+    return new Set(inputs.map((input) => input.prevout?.address).filter((address) => Boolean(address)));
+}
+function singleInputAddress(inputs) {
+    const addresses = inputAddresses(inputs);
+    return addresses.size === 1 ? [...addresses][0] : undefined;
+}
+function inputAddressEndpoint(inputs) {
+    const addresses = [...inputAddresses(inputs)];
+    if (addresses.length === 0) {
+        return undefined;
+    }
+    return addresses.length === 1 ? { address: addresses[0] } : { addresses };
+}
+function nativeTbcSourceInputs(inputs, ftMovements) {
+    // FT transactions may include protocol inputs; prefer ordinary spendable inputs as native TBC sources.
+    if (ftMovements.length === 0) {
+        return inputs;
+    }
+    const nativeInputs = inputs.filter((input) => input.prevout?.script.type === ScriptType.P2PKH ||
+        input.prevout?.script.type === ScriptType.MULTISIG);
+    return nativeInputs.length > 0 ? nativeInputs : inputs;
+}
+export function normalizeActionType(transactionType) {
+    // Convert display-oriented transaction types into stable camelCase action keys.
+    const normalized = transactionType
+        .replace(/OrderBook/gu, 'Order Book')
+        .replace(/PoolNFT/gu, 'Pool NFT')
+        .replace(/StableCoin/gu, 'Stable Coin')
+        .replace(/\/+/gu, ' ')
+        .replace(/[^a-z0-9]+/giu, ' ')
+        .trim()
+        .split(/\s+/u)
+        .map((part, index) => {
+        const lower = part.toLowerCase();
+        return index === 0 ? lower : `${lower.charAt(0).toUpperCase()}${lower.slice(1)}`;
+    })
+        .join('');
+    return normalized || 'transaction';
+}
+function tokenTransactionAsset(movement) {
+    return {
+        type: movement.isStableCoin ? 'stablecoin' : 'ft',
+        symbol: movement.symbol,
+        name: movement.name,
+        contractId: movement.contractId,
+        decimal: movement.decimal,
+    };
+}
+function tokenTransactionAmount(movement) {
+    return {
+        raw: movement.rawAmount,
+        display: movement.displayAmount,
+        decimal: movement.decimal,
+    };
+}
+function semanticAssetToTransactionAsset(asset) {
+    // Semantics use abstract asset types; asset flows map them back to the public result model.
+    if (asset.type === 'native') {
+        return NATIVE_TBC_ASSET;
+    }
+    if (asset.type === 'nftCollection') {
+        return {
+            type: 'nftCollection',
+            name: asset.name,
+            collectionId: asset.collectionId,
+            contractId: asset.contractId,
+        };
+    }
+    if (asset.type === 'nft') {
+        if (asset.subtype === 'poolNft') {
+            return {
+                type: 'nft',
+                subtype: 'poolNft',
+                contractId: asset.contractId,
+                poolNft: asset.poolNft,
+            };
+        }
+        return {
+            type: 'nft',
+            symbol: asset.symbol,
+            name: asset.name,
+            collectionId: asset.collectionId,
+            contractId: asset.contractId,
+        };
+    }
+    return {
+        type: asset.type,
+        symbol: asset.symbol,
+        name: asset.name,
+        contractId: asset.contractId,
+        decimal: asset.decimal,
+    };
+}
+function semanticAmountToTransactionAmount(amount) {
+    if (amount.satoshis !== undefined) {
+        return { satoshis: amount.satoshis };
+    }
+    return {
+        raw: amount.rawAmount ?? '0',
+        display: amount.displayAmount,
+        decimal: amount.decimal,
+    };
+}
+function semanticEffectPurpose(effect, isOrderBook) {
+    switch (effect.kind) {
+        case 'mint':
+            return 'mint';
+        case 'state':
+            return 'state';
+        case 'fee':
+            return isOrderBook ? 'transfer' : 'fee';
+        case 'orderLock':
+            return 'lock';
+        case 'orderRelease':
+            return 'release';
+        case 'self':
+            return 'self';
+        default:
+            return 'transfer';
+    }
+}
+function orderBookSemanticContext(semantic) {
+    const hasOrderBookRelation = semantic.relations.some((relation) => relation.kind.startsWith('orderBook'));
+    if (!hasOrderBookRelation) {
+        return undefined;
+    }
+    const action = ORDER_BOOK_ACTION_BY_TYPE[semantic.type];
+    return {
+        protocol: 'orderBook',
+        recognized: true,
+        ...(action ? { action } : {}),
+    };
+}
+function endpoint(value) {
+    // Remove undefined fields so public results never expose empty endpoint shells.
+    if (!value) {
+        return undefined;
+    }
+    const publicEndpoint = withoutUndefinedValues({
+        address: value.address,
+        addresses: value.addresses && value.addresses.length > 0 ? value.addresses : undefined,
+        hash: value.hash,
+        poolId: value.poolId,
+        txid: value.txid,
+        vout: value.vout,
+        script: value.script ? withoutUndefinedValues(value.script) : undefined,
+    });
+    return Object.values(publicEndpoint).some((item) => item !== undefined) ? publicEndpoint : undefined;
+}
+function nativeOutputEndpoint(output) {
+    const address = output.address;
+    const hash = address ? undefined : output.script.data?.hash;
+    const script = address || hash
+        ? undefined
+        : {
+            hex: output.script.hex,
+            asm: output.script.asm,
+        };
+    return endpoint({ address, hash, script });
+}
+function withoutUndefinedValues(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function directionForFlow(purpose, from, to) {
+    // Direction is a display hint and is conservatively inferred from purpose, source, and destination.
+    if (purpose === 'self' || purpose === 'state') {
+        return 'self';
+    }
+    if (purpose === 'mint' || purpose === 'release') {
+        return 'in';
+    }
+    if (purpose === 'burn' || purpose === 'fee' || purpose === 'lock') {
+        return 'out';
+    }
+    if (purpose === 'transfer' && to?.script) {
+        return 'out';
+    }
+    const fromAddresses = [
+        ...(from?.address ? [from.address] : []),
+        ...(from?.addresses ?? []),
+    ];
+    const fromOwners = [
+        ...fromAddresses,
+        ...(from?.hash ? [from.hash] : []),
+        ...(from?.poolId ? [from.poolId] : []),
+    ];
+    const toOwner = to?.address ?? to?.hash ?? to?.poolId;
+    if (fromOwners.length > 0 && toOwner) {
+        return fromOwners.includes(toOwner) ? 'self' : 'out';
+    }
+    if (purpose === 'transfer' && toOwner) {
+        return 'out';
+    }
+    return 'unknown';
+}
+function unsupportedOutputContexts(unsupported) {
+    const markersByOutput = new Map();
+    for (const item of unsupported) {
+        if (item.outputIndex === undefined) {
+            continue;
+        }
+        const markers = markersByOutput.get(item.outputIndex) ?? new Set();
+        if (item.marker) {
+            markers.add(item.marker);
+        }
+        markersByOutput.set(item.outputIndex, markers);
+    }
+    return new Map([...markersByOutput].map(([outputIndex, markers]) => [
+        outputIndex,
+        {
+            protocol: 'unknown',
+            recognized: false,
+            ...(markers.size ? { markers: [...markers].sort() } : {}),
+        },
+    ]));
+}
+function hasAssetFlowAmount(flow) {
+    return flow.amount !== undefined;
+}
+function assetFlowAggregationKey(flow) {
+    const amountKind = 'satoshis' in flow.amount ? 'satoshis' : 'raw';
+    return JSON.stringify({
+        purpose: flow.purpose,
+        direction: flow.direction,
+        asset: flow.asset,
+        from: flow.from,
+        to: flow.to,
+        context: flow.context,
+        amountKind,
+    });
+}
+function canAggregateAssetFlow(flow) {
+    if ('satoshis' in flow.amount) {
+        return flow.asset.type === 'tbc';
+    }
+    return flow.asset.type === 'ft' || flow.asset.type === 'stablecoin';
+}
+function aggregateAssetFlowAmount(target, source) {
+    if ('satoshis' in target.amount && 'satoshis' in source.amount) {
+        target.amount = { satoshis: target.amount.satoshis + source.amount.satoshis };
+        return;
+    }
+    if ('raw' in target.amount && 'raw' in source.amount) {
+        const raw = (BigInt(target.amount.raw) + BigInt(source.amount.raw)).toString();
+        const decimal = target.amount.decimal ?? source.amount.decimal;
+        target.amount = {
+            raw,
+            display: decimal === undefined ? undefined : formatTokenRawAmount(raw, decimal),
+            decimal,
+        };
+    }
+}
+function aggregateAssetFlows(flows) {
+    // Aggregate TBC or FT flows with the same asset, endpoints, and purpose to avoid fragmented multi-output displays.
+    const aggregated = [];
+    const flowByKey = new Map();
+    for (const flow of flows) {
+        if (!hasAssetFlowAmount(flow) || !canAggregateAssetFlow(flow)) {
+            aggregated.push(flow);
+            continue;
+        }
+        const key = assetFlowAggregationKey(flow);
+        const existing = flowByKey.get(key);
+        if (existing) {
+            aggregateAssetFlowAmount(existing, flow);
+            continue;
+        }
+        flowByKey.set(key, flow);
+        aggregated.push(flow);
+    }
+    return aggregated;
+}
+function buildNativeAssetFlows(inputs, outputs, transactionType, ftMovements, protocolNativeOutputIndexes = new Set(), nativeFtCarrierOutputIndexes = new Set(), unsupportedContexts = new Map()) {
+    // Native TBC flows cover ordinary transfers and significant TBC value carried by protocol transactions.
+    const sourceInputs = nativeTbcSourceInputs(inputs, ftMovements);
+    const sourceEndpoint = inputAddressEndpoint(sourceInputs);
+    const sourceAddresses = inputAddresses(sourceInputs);
+    const firstFtReceiver = ftMovements[0]?.receiver;
+    const nativeOutputs = outputs.filter((output) => isNativeTbcFlowOutput(output, protocolNativeOutputIndexes, nativeFtCarrierOutputIndexes));
+    if (transactionType === 'TBC coinbase') {
+        return nativeOutputs.map((output) => {
+            const purpose = 'mint';
+            const to = nativeOutputEndpoint(output);
+            return {
+                purpose,
+                direction: directionForFlow(purpose, undefined, to),
+                asset: NATIVE_TBC_ASSET,
+                amount: { satoshis: output.satoshis },
+                ...(to ? { to } : {}),
+            };
+        });
+    }
+    const allOutputsReturnToInputs = Boolean(sourceAddresses.size) &&
+        nativeOutputs.length > 0 &&
+        nativeOutputs.every((output) => Boolean(isAddressLikeNativeOutput(output) && output.address && sourceAddresses.has(output.address)));
+    return nativeOutputs
+        .map((output) => {
+        const context = unsupportedContexts.get(output.index);
+        const isChange = Boolean(output.address && sourceAddresses.has(output.address));
+        const isSelfAnnotatedOutput = Boolean(isChange && output.script.asm.includes('OP_RETURN'));
+        let purpose = context ? 'transfer' : 'unknown';
+        if (!context && sourceAddresses.size) {
+            if (isSelfAnnotatedOutput || allOutputsReturnToInputs) {
+                purpose = 'self';
+            }
+            else if (allOutputsReturnToInputs ||
+                isChange ||
+                (ftMovements.length > 0 &&
+                    transactionType !== 'TBC transfer' &&
+                    firstFtReceiver !== undefined &&
+                    Boolean(output.address) &&
+                    output.address !== firstFtReceiver)) {
+                purpose = 'self';
+            }
+            else {
+                purpose = 'transfer';
+            }
+        }
+        const from = endpoint(purpose === 'transfer' ? sourceEndpoint : undefined);
+        const to = nativeOutputEndpoint(output);
+        return {
+            purpose,
+            direction: context ? 'out' : directionForFlow(purpose, from, to),
+            asset: NATIVE_TBC_ASSET,
+            amount: { satoshis: output.satoshis },
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+            ...(context ? { context } : {}),
+        };
+    });
+}
+export function isNativeTbcFlowOutput(output, protocolNativeOutputIndexes, nativeProtocolCarrierOutputIndexes = new Set()) {
+    // Protocol state outputs are not native flows by default, but high-value carriers remain explicit TBC flows.
+    if (output.satoshis <= 0) {
+        return false;
+    }
+    if (nativeProtocolCarrierOutputIndexes.has(output.index)) {
+        return true;
+    }
+    if (protocolNativeOutputIndexes.has(output.index)) {
+        return false;
+    }
+    const isPlainP2pkh = output.scriptKind === 'p2pkh' && !output.script.asm.includes('OP_RETURN');
+    if (!isPlainP2pkh && output.satoshis < MIN_NON_STANDARD_TBC_FLOW_SATOSHIS) {
+        return false;
+    }
+    if (output.scriptKind === 'p2pkh') {
+        return true;
+    }
+    if (output.scriptKind === 'multisig') {
+        return true;
+    }
+    if (output.scriptKind === 'op_return') {
+        return false;
+    }
+    return true;
+}
+function isAddressLikeNativeOutput(output) {
+    return output.scriptKind === 'p2pkh' || output.scriptKind === 'multisig';
+}
+function buildFtAssetFlows(inputs, outputs, transactionType, movements) {
+    // Build FT asset flows from verified movements, never directly from FTape markers.
+    const sourceAddress = firstInputAddress(inputs);
+    const sourceOwnerEndpoint = ftInputOwnerEndpoint(inputs, outputs);
+    return movements.map((movement, index) => {
+        const to = endpoint({
+            address: movement.receiver,
+            hash: movement.receiverHash,
+            outputIndex: movement.outputIndex,
+            tapeOutputIndex: movement.tapeOutputIndex,
+        });
+        const isMint = index === 0 && transactionType.endsWith('mint');
+        const candidateFrom = endpoint(index === 0 ? (sourceOwnerEndpoint ?? { address: sourceAddress }) : undefined);
+        const purpose = index > 0
+            ? 'self'
+            : isMint
+                ? 'mint'
+                : transactionType.endsWith('merge') && directionForFlow('transfer', candidateFrom, to) === 'self'
+                    ? 'self'
+                    : 'transfer';
+        const from = isMint ? undefined : candidateFrom;
+        return {
+            purpose,
+            direction: directionForFlow(purpose, from, to),
+            asset: tokenTransactionAsset(movement),
+            amount: tokenTransactionAmount(movement),
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+        };
+    });
+}
+function buildSemanticAssetFlows(semantic) {
+    // Derive asset flows for complex protocols such as OrderBook from semantic effects to avoid duplicate inference.
+    const orderBookContext = orderBookSemanticContext(semantic);
+    const publicEffects = orderBookContext
+        ? semantic.effects.filter((effect) => effect.kind !== 'state')
+        : semantic.effects;
+    return publicEffects.map((effect) => {
+        const purpose = semanticEffectPurpose(effect, Boolean(orderBookContext));
+        const context = purpose === 'lock' ? orderBookContext : undefined;
+        const from = endpoint({ address: effect.from?.address, inputIndex: effect.inputIndex });
+        const to = endpoint({
+            address: effect.to?.address,
+            outputIndex: effect.outputIndex,
+            tapeOutputIndex: effect.tapeOutputIndex,
+        });
+        const asset = semanticAssetToTransactionAsset(effect.asset);
+        if (asset.type === 'nftCollection') {
+            return {
+                purpose: 'mint',
+                direction: 'in',
+                asset,
+                ...(to ? { to } : {}),
+                ...(context ? { context } : {}),
+            };
+        }
+        if (asset.type === 'nft') {
+            return {
+                purpose,
+                direction: directionForFlow(purpose, from, to),
+                asset,
+                ...(from ? { from } : {}),
+                ...(to ? { to } : {}),
+                ...(context ? { context } : {}),
+            };
+        }
+        return {
+            purpose,
+            direction: directionForFlow(purpose, from, to),
+            asset,
+            amount: semanticAmountToTransactionAmount(effect.amount),
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+            ...(context ? { context } : {}),
+        };
+    });
+}
+function poolNftTokenAsset(movement) {
+    return {
+        type: 'ft',
+        symbol: movement.ftSymbol ?? 'FT',
+        name: movement.ftName,
+        contractId: movement.ftTokenId ?? movement.ftContractTxid,
+        decimal: movement.ftDecimal,
+    };
+}
+function poolNftLpAsset(movement) {
+    const asset = {
+        type: 'ft',
+        symbol: movement.ftSymbol ? `${movement.ftSymbol}-LP` : 'LP',
+        name: movement.ftName ? `${movement.ftName} LP` : undefined,
+        decimal: movement.ftDecimal,
+    };
+    if (!movement.poolId) {
+        return asset;
+    }
+    return {
+        ...asset,
+        subtype: 'poolLp',
+        poolId: movement.poolId,
+    };
+}
+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 poolNftRawAmount(raw, decimal) {
+    return {
+        raw,
+        display: decimal === undefined ? undefined : formatTokenRawAmount(raw, decimal),
+        decimal,
+    };
+}
+function poolNftPoolEndpoint(movement) {
+    const pool = endpoint({ poolId: movement.poolId });
+    if (pool) {
+        return pool;
+    }
+    return endpoint({
+        address: movement.poolStateAddress,
+        hash: movement.poolStateAddress ? undefined : movement.poolStateHash,
+        outputIndex: movement.poolStateOutputIndex ?? movement.poolOutputIndex,
+        tapeOutputIndex: movement.tapeOutputIndex,
+    });
+}
+function poolNftReceiverEndpoint(movement) {
+    return endpoint({
+        address: movement.receiver,
+        hash: movement.receiver ? undefined : movement.receiverHash,
+    });
+}
+function poolNftSenderEndpoint(movement) {
+    if (movement.action === 'mergeFtInPool') {
+        return poolNftPoolEndpoint(movement);
+    }
+    return endpoint({
+        address: movement.sender,
+        hash: movement.senderHash,
+    });
+}
+function poolNftFeeEndpoint(feeOutput) {
+    return endpoint({
+        address: feeOutput.address,
+        outputIndex: feeOutput.outputIndex,
+    });
+}
+function buildPoolNftAssetFlows(movement) {
+    const flows = [];
+    const pool = poolNftPoolEndpoint(movement);
+    const receiver = poolNftReceiverEndpoint(movement);
+    const sender = poolNftSenderEndpoint(movement);
+    const userIn = sender ?? receiver;
+    const userOut = receiver ?? sender;
+    const tokenAsset = poolNftTokenAsset(movement);
+    const lpAsset = poolNftLpAsset(movement);
+    const createAsset = poolNftCreateAsset(movement);
+    if (createAsset) {
+        const to = endpoint({
+            txid: movement.contractId,
+            vout: movement.poolStateOutputIndex ?? movement.poolOutputIndex ?? 0,
+        });
+        flows.push({
+            purpose: 'mint',
+            direction: 'in',
+            asset: createAsset,
+            ...(to ? { to } : {}),
+        });
+    }
+    if (movement.tbcInSatoshis !== undefined && movement.tbcInSatoshis > 0) {
+        const purpose = 'transfer';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, userIn, pool),
+            asset: NATIVE_TBC_ASSET,
+            amount: { satoshis: movement.tbcInSatoshis },
+            ...(userIn ? { from: userIn } : {}),
+            ...(pool ? { to: pool } : {}),
+        });
+    }
+    if (movement.tbcOutSatoshis !== undefined && movement.tbcOutSatoshis > 0) {
+        const purpose = 'transfer';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, pool, receiver),
+            asset: NATIVE_TBC_ASSET,
+            amount: { satoshis: movement.tbcOutSatoshis },
+            ...(pool ? { from: pool } : {}),
+            ...(userOut ? { to: userOut } : {}),
+        });
+    }
+    if (movement.ftInRawAmount) {
+        const purpose = movement.action === 'mergeFtInPool' &&
+            directionForFlow('transfer', userIn, pool) === 'self'
+            ? 'self'
+            : 'transfer';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, userIn, pool),
+            asset: tokenAsset,
+            amount: poolNftRawAmount(movement.ftInRawAmount, movement.ftDecimal),
+            ...(userIn ? { from: userIn } : {}),
+            ...(pool ? { to: pool } : {}),
+        });
+    }
+    if (movement.ftOutRawAmount) {
+        const purpose = 'transfer';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, pool, receiver),
+            asset: tokenAsset,
+            amount: poolNftRawAmount(movement.ftOutRawAmount, movement.ftDecimal),
+            ...(pool ? { from: pool } : {}),
+            ...(userOut ? { to: userOut } : {}),
+        });
+    }
+    if (movement.ftLpInRawAmount) {
+        const purpose = 'burn';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, userIn, undefined),
+            asset: lpAsset,
+            amount: poolNftRawAmount(movement.ftLpInRawAmount, movement.ftDecimal),
+            ...(userIn ? { from: userIn } : {}),
+        });
+    }
+    if (movement.ftLpOutRawAmount) {
+        const purpose = 'mint';
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, undefined, userOut),
+            asset: lpAsset,
+            amount: poolNftRawAmount(movement.ftLpOutRawAmount, movement.ftDecimal),
+            ...(userOut ? { to: userOut } : {}),
+        });
+    }
+    for (const feeOutput of movement.feeOutputs ?? []) {
+        const purpose = 'transfer';
+        const to = poolNftFeeEndpoint(feeOutput);
+        flows.push({
+            purpose,
+            direction: directionForFlow(purpose, userIn, to),
+            asset: NATIVE_TBC_ASSET,
+            amount: { satoshis: feeOutput.satoshis },
+            ...(userIn ? { from: userIn } : {}),
+            ...(to ? { to } : {}),
+        });
+    }
+    return flows;
+}
+function buildProtocolAssetFlows(nftMovements, piggyBankMovements, poolNftMovements) {
+    // Add protocol-specific non-FT flows here; native TBC carriers are handled separately below.
+    const piggyBankFlows = piggyBankMovements.map((movement) => {
+        const purpose = movement.action === 'unfreeze' ? 'release' : 'lock';
+        const from = endpoint(movement.action === 'unfreeze'
+            ? {
+                address: movement.address,
+                inputIndex: movement.inputIndex,
+            }
+            : undefined);
+        const to = endpoint({
+            address: movement.receiver ?? movement.address,
+            outputIndex: movement.action === 'unfreeze' ? movement.releaseOutputIndex : movement.outputIndex,
+        });
+        return {
+            purpose,
+            direction: directionForFlow(purpose, from, to),
+            asset: NATIVE_TBC_ASSET,
+            amount: { satoshis: movement.releasedSatoshis ?? movement.satoshis },
+            context: {
+                protocol: 'piggyBank',
+                recognized: true,
+                action: movement.action,
+            },
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+        };
+    });
+    const nftFlows = nftMovements.map((movement) => {
+        if (movement.action === 'mintCollection') {
+            const to = endpoint({ address: movement.mintSlotAddress });
+            return {
+                purpose: 'mint',
+                direction: 'in',
+                asset: {
+                    type: 'nftCollection',
+                    name: movement.collectionName,
+                    collectionId: movement.collectionId,
+                    contractId: movement.contractId,
+                },
+                ...(to ? { to } : {}),
+            };
+        }
+        const purpose = movement.action === 'burn'
+            ? 'burn'
+            : movement.action === 'transfer'
+                ? 'transfer'
+                : 'mint';
+        const from = endpoint({
+            address: movement.sender,
+        });
+        const to = movement.action === 'burn'
+            ? undefined
+            : endpoint({
+                address: movement.receiver,
+                outputIndex: movement.outputIndex,
+                tapeOutputIndex: movement.tapeOutputIndex,
+            });
+        const asset = {
+            type: 'nft',
+            symbol: movement.symbol,
+            name: movement.nftName,
+            contractId: movement.contractId,
+            ...(movement.collectionId ? { collectionId: movement.collectionId } : {}),
+        };
+        return {
+            purpose,
+            direction: directionForFlow(purpose, from, to),
+            asset,
+            ...(from ? { from } : {}),
+            ...(to ? { to } : {}),
+        };
+    });
+    const poolFlows = poolNftMovements.flatMap(buildPoolNftAssetFlows);
+    return [...piggyBankFlows, ...nftFlows, ...poolFlows];
+}
+function poolNftExplainedFtOutputIndexes(poolNftMovements) {
+    return new Set(poolNftMovements.flatMap((movement) => [
+        movement.ftInOutputIndex,
+        movement.ftOutOutputIndex,
+        movement.ftLpInOutputIndex,
+        movement.ftLpOutOutputIndex,
+    ]).filter((index) => index !== undefined));
+}
+function isPoolNftStateFtMovement(ftMovement, poolNftMovements) {
+    return poolNftMovements.some((poolMovement) => {
+        const locksToPoolState = (ftMovement.receiverHash !== undefined && ftMovement.receiverHash === poolMovement.poolStateHash) ||
+            (ftMovement.receiver !== undefined && ftMovement.receiver === poolMovement.poolStateAddress);
+        if (!locksToPoolState) {
+            return false;
+        }
+        const ftContractTxid = poolMovement.ftTokenId ?? poolMovement.ftContractTxid;
+        return !ftContractTxid || !ftMovement.contractId || ftMovement.contractId === ftContractTxid;
+    });
+}
+function isPoolNftLpCodeOutput(ftMovement, outputs) {
+    const output = outputs.find((candidate) => candidate.index === ftMovement.outputIndex);
+    return Boolean(output?.script.hex?.toLowerCase().endsWith(FTLP_CODE_MARKER_HEX));
+}
+function isPoolNftLpChangeMovement(ftMovement, outputs, poolNftMovements) {
+    if (!isPoolNftLpCodeOutput(ftMovement, outputs)) {
+        return false;
+    }
+    return poolNftMovements.some((poolMovement) => poolMovement.action === 'consumeLiquidity' &&
+        ftMovement.outputIndex !== poolMovement.ftOutOutputIndex &&
+        ftMovement.outputIndex !== poolMovement.ftLpInOutputIndex);
+}
+function poolNftStateCarrierOutputIndexes(outputs) {
+    // A decoded PoolNFT tape describes the adjacent contract output even when the
+    // action matcher cannot safely classify the transaction. Keep that state UTXO
+    // out of generic native flows rather than exposing its locking script as a payee.
+    const outputByIndex = new Map(outputs.map((output) => [output.index, output]));
+    return outputs.flatMap((tapeOutput) => {
+        if (!tapeOutput.script.data?.poolNft) {
+            return [];
+        }
+        const stateCarrier = outputByIndex.get(tapeOutput.index - 1);
+        return stateCarrier?.scriptKind === 'contract' ? [stateCarrier.index] : [];
+    });
+}
+export function buildAssetFlows(transactionType, inputs, outputs, ftMovements, nftMovements, piggyBankMovements, poolNftMovements, orderBookOrders, semantic, unsupported = []) {
+    // Asset flows are the core public display layer for observable protocol assets and native TBC movements.
+    // Contract state remains available from decoded chain inputs and outputs and internal semantic evidence.
+    if (orderBookOrders.length) {
+        return aggregateAssetFlows(buildSemanticAssetFlows(semantic));
+    }
+    const protocolNativeOutputIndexes = new Set([
+        ...nftMovements.flatMap((movement) => [movement.outputIndex, movement.holdOutputIndex]),
+        ...piggyBankMovements.flatMap((movement) => [movement.outputIndex, movement.releaseOutputIndex]),
+        ...poolNftMovements.map((movement) => movement.poolOutputIndex),
+        ...poolNftMovements.map((movement) => movement.tbcOutOutputIndex),
+        ...poolNftMovements.flatMap((movement) => (movement.feeOutputs ?? []).map((feeOutput) => feeOutput.outputIndex)),
+        ...poolNftStateCarrierOutputIndexes(outputs),
+    ].filter((index) => index !== undefined));
+    const explainedFtOutputIndexes = poolNftExplainedFtOutputIndexes(poolNftMovements);
+    const ftMovementsForAssetFlows = ftMovements.filter((movement) => !explainedFtOutputIndexes.has(movement.outputIndex) &&
+        !isPoolNftStateFtMovement(movement, poolNftMovements) &&
+        !isPoolNftLpChangeMovement(movement, outputs, poolNftMovements));
+    const nativeProtocolCarrierOutputIndexes = new Set([
+        ...ftMovements.flatMap((movement) => [
+            (outputs[movement.outputIndex]?.satoshis ?? 0) >= MIN_NON_STANDARD_TBC_FLOW_SATOSHIS
+                ? movement.outputIndex
+                : undefined,
+            (outputs[movement.tapeOutputIndex]?.satoshis ?? 0) >= MIN_NON_STANDARD_TBC_FLOW_SATOSHIS
+                ? movement.tapeOutputIndex
+                : undefined,
+        ]),
+        ...nftMovements.flatMap((movement) => [
+            movement.outputIndex !== undefined && (outputs[movement.outputIndex]?.satoshis ?? 0) >= MIN_NON_STANDARD_TBC_FLOW_SATOSHIS
+                ? movement.outputIndex
+                : undefined,
+            movement.holdOutputIndex !== undefined && (outputs[movement.holdOutputIndex]?.satoshis ?? 0) >= MIN_NON_STANDARD_TBC_FLOW_SATOSHIS
+                ? movement.holdOutputIndex
+                : undefined,
+            movement.tapeOutputIndex !== undefined && (outputs[movement.tapeOutputIndex]?.satoshis ?? 0) >= MIN_NON_STANDARD_TBC_FLOW_SATOSHIS
+                ? movement.tapeOutputIndex
+                : undefined,
+        ]),
+    ].filter((index) => index !== undefined));
+    return aggregateAssetFlows([
+        ...buildFtAssetFlows(inputs, outputs, transactionType, ftMovementsForAssetFlows),
+        ...buildProtocolAssetFlows(nftMovements, piggyBankMovements, poolNftMovements),
+        ...buildNativeAssetFlows(inputs, outputs, transactionType, ftMovements, protocolNativeOutputIndexes, nativeProtocolCarrierOutputIndexes, unsupportedOutputContexts(unsupported)),
+    ]);
+}
+//# sourceMappingURL=index.js.map