wallet-storage/src/storage/methods/getBeefForTransaction.ts

BRC100 conforming wallet, wallet storage and wallet signer components

import { Beef } from '@bsv/sdk'
import { asBsvSdkTx, entity, sdk, StorageProvider, verifyTruthy } from '../../index.client'

/**
 * Creates a `Beef` to support the validity of a transaction identified by its `txid`.
 * 
 * `storage` is used to retrieve proven transactions and their merkle paths,
 * or proven_tx_req record with beef of external inputs (internal inputs meged by recursion).
 * Otherwise external services are used.
 * 
 * `options.maxRecursionDepth` can be set to prevent overly deep chained dependencies. Will throw ERR_EXTSVS_ENVELOPE_DEPTH if exceeded.
 * 
 * If `trustSelf` is true, a partial `Beef` will be returned where transactions known by `storage` to
 * be valid by verified proof are represented solely by 'txid'.
 * 
 * If `knownTxids` is defined, any 'txid' required by the `Beef` that appears in the array is represented solely as a 'known' txid. 
 * 
 * @param storage the chain on which txid exists.
 * @param txid the transaction hash for which an envelope is requested.
 * @param options
 */
export async function getBeefForTransaction(storage: StorageProvider, txid: string, options: sdk.StorageGetBeefOptions) : Promise<Beef>
{
    const beef =
        // deserialize mergeToBeef if it is an array
        Array.isArray(options.mergeToBeef) ? Beef.fromBinary(options.mergeToBeef)
        // otherwise if undefined create a new Beef
        : (options.mergeToBeef || new Beef())

    await mergeBeefForTransactionRecurse(beef, storage, txid, options, 0)

    return beef
}

/**
 * @returns rawTx if txid known to network, if merkle proof available then also proven result is valid.
 */
async function getProvenOrRawTxFromServices(storage: StorageProvider, txid: string, options: sdk.StorageGetBeefOptions): Promise<sdk.ProvenOrRawTx> {
    const services = storage.getServices();
    const por = await entity.ProvenTx.fromTxid(txid, await storage.getServices());
    if (por.proven && !options.ignoreStorage && !options.ignoreNewProven) {
        por.proven.provenTxId = await storage.insertProvenTx(por.proven.toApi());
    }
    return { proven: por.proven?.toApi(), rawTx: por.rawTx };
}

async function mergeBeefForTransactionRecurse(
    beef: Beef,
    storage: StorageProvider,
    txid: string,
    options: sdk.StorageGetBeefOptions,
    recursionDepth: number
): Promise<Beef> {
    const maxDepth = storage.maxRecursionDepth;
    if (maxDepth && maxDepth <= recursionDepth) throw new sdk.WERR_INVALID_OPERATION(`Maximum BEEF depth exceeded. Limit is ${storage.maxRecursionDepth}`);

    if (options.knownTxids && options.knownTxids.indexOf(txid) > -1) {
        // This txid is one of the txids the caller claims to already know are valid...
        beef.mergeTxidOnly(txid);
        return beef
    }

    if (!options.ignoreStorage) {
        // if we can use storage, ask storage if it has the txid
        const knownBeef = await storage.getValidBeefForTxid(txid, beef, options.trustSelf, options.knownTxids)
        if (knownBeef)
            return knownBeef
    }

    if (options.ignoreServices)
        throw new sdk.WERR_INVALID_PARAMETER(`txid ${txid}`, `valid transaction on chain ${storage.chain}`);

    // if storage doesn't know about txid, use services
    // to find it and if it has a proof, remember it.
    const r = await getProvenOrRawTxFromServices(storage, txid, options);

    if (r.proven && options.minProofLevel && options.minProofLevel > recursionDepth) {
        // ignore proof at this recursion depth
        r.proven = undefined;
    }

    if (r.proven) {
        // storage has proven this txid,
        // merge both the raw transaction and its merkle path
        beef.mergeRawTx(r.proven.rawTx);
        beef.mergeBump(new entity.ProvenTx(r.proven).getMerklePath());
        return beef
    }
    
    if (!r.rawTx)
        throw new sdk.WERR_INVALID_PARAMETER(`txid ${txid}`, `valid transaction on chain ${storage.chain}`);

    // merge the raw transaction and recurse over its inputs.
    beef.mergeRawTx(r.rawTx!);
    // recurse inputs
    const tx = asBsvSdkTx(r.rawTx!);
    for (const input of tx.inputs) {
        const inputTxid = verifyTruthy(input.sourceTXID);
        if (!beef.findTxid(inputTxid)) {
            // Only if the txid is not already in the list of beef transactions.
            await mergeBeefForTransactionRecurse(beef, storage, inputTxid, options, recursionDepth + 1);
        }
    }

    return beef
}