Transaction Input

Overview

The TransactionInput class in the BSV TypeScript SDK represents an input to a Bitcoin transaction. Each input references an unspent transaction output (UTXO) from a previous transaction and includes an unlocking script (scriptSig) that proves the right to spend those coins. Understanding transaction inputs is fundamental to building and validating Bitcoin transactions.

Purpose

Reference unspent transaction outputs (UTXOs) from previous transactions
Store unlocking scripts (formerly called scriptSig) that prove spending authority
Maintain sequence numbers for transaction replacement and timelocks
Support SPV (Simplified Payment Verification) with merkle proofs
Handle various input types (P2PKH, P2PK, custom scripts, etc.)
Serialize and deserialize inputs for transaction broadcasting
Enable transaction signing and validation workflows

Basic Usage

import { Transaction, TransactionInput, PrivateKey, P2PKH } from '@bsv/sdk';

// Create a transaction with an input
const privKey = PrivateKey.fromWif('L5EY1SbTvvPNSdCYQe1EJHfXCBBT4PmnF6CDbzCm9iifZptUvDGB');

// Reference to previous transaction
const sourceTransaction = Transaction.fromHex('0100000001...');
const sourceOutputIndex = 0;

// Create input with unlocking script template
const input: TransactionInput = {
  sourceTransaction,
  sourceOutputIndex,
  unlockingScriptTemplate: new P2PKH().unlock(privKey),
  sequence: 0xffffffff // Default sequence number
};

// Create transaction and add input
const tx = new Transaction();
tx.addInput(input);

// The unlocking script will be populated during signing
await tx.sign();

console.log('Input added:', tx.inputs[0]);
console.log('Unlocking script:', tx.inputs[0].unlockingScript?.toHex());

Key Features

1. Creating Transaction Inputs with Source References

Inputs reference previous transaction outputs (UTXOs):

import { Transaction, TransactionInput, PrivateKey, P2PKH } from '@bsv/sdk';

// Create input referencing a specific UTXO
const privKey = PrivateKey.fromWif('L5EY1SbTvvPNSdCYQe1EJHfXCBBT4PmnF6CDbzCm9iifZptUvDGB');

// Option 1: Full source transaction (for SPV)
const sourceTransaction = Transaction.fromHex('0100000001...');
const input1: TransactionInput = {
  sourceTransaction,
  sourceOutputIndex: 0, // Which output of the source transaction
  unlockingScriptTemplate: new P2PKH().unlock(privKey)
};

// Option 2: Just the TXID (requires trusted validation)
const input2: TransactionInput = {
  sourceTXID: '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b',
  sourceOutputIndex: 1,
  unlockingScriptTemplate: new P2PKH().unlock(privKey)
};

// Option 3: With source satoshis and locking script (lightweight SPV)
const input3: TransactionInput = {
  sourceTXID: '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b',
  sourceOutputIndex: 0,
  sourceSatoshis: 10000,
  lockingScript: new P2PKH().lock('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'),
  unlockingScriptTemplate: new P2PKH().unlock(
    privKey,
    'all',
    false,
    10000
  )
};

// Add inputs to transaction
const tx = new Transaction();
tx.addInput(input1);
tx.addInput(input2);
tx.addInput(input3);

console.log('Transaction has', tx.inputs.length, 'inputs');

2. Unlocking Script Templates

Unlocking scripts prove the right to spend UTXOs:

import { Transaction, PrivateKey, P2PKH, Script, OP } from '@bsv/sdk';

const privKey = PrivateKey.fromWif('L5EY1SbTvvPNSdCYQe1EJHfXCBBT4PmnF6CDbzCm9iifZptUvDGB');
const sourceTransaction = Transaction.fromHex('...');

// Standard P2PKH unlocking
const p2pkhInput = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey)
};

// P2PKH with custom sighash flags
const customSighashInput = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(
    privKey,
    'single', // signOutputs: 'all' | 'none' | 'single'
    true,     // anyoneCanPay: allows others to add inputs
    10000,    // sourceSatoshis
    new P2PKH().lock('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa') // lockingScript
  )
};

// Custom unlocking script template
import { ScriptTemplate, UnlockingScript, LockingScript } from '@bsv/sdk';

class CustomUnlock implements Partial<ScriptTemplate> {
  unlock(secret: Buffer) {
    return {
      sign: async (tx: Transaction, inputIndex: number) => {
        // Create custom unlocking script
        return new Script()
          .writeBin(secret)
          .writeBin(Buffer.from('additional_data'));
      },
      estimateLength: async () => {
        return 100; // Estimated length in bytes
      }
    };
  }
}

const customInput = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new CustomUnlock().unlock(Buffer.from('my_secret'))
};

// Add inputs to transaction
const tx = new Transaction();
tx.addInput(p2pkhInput);
tx.addInput(customSighashInput);
tx.addInput(customInput);

// Sign transaction (populates unlocking scripts)
await tx.sign();

console.log('All inputs signed');

3. Sequence Numbers and Time Locks

Sequence numbers enable transaction replacement and relative time locks:

import { Transaction, PrivateKey, P2PKH } from '@bsv/sdk';

const privKey = PrivateKey.fromWif('L5EY1SbTvvPNSdCYQe1EJHfXCBBT4PmnF6CDbzCm9iifZptUvDGB');
const sourceTransaction = Transaction.fromHex('...');

// Default sequence (0xffffffff) - final, no replacement
const finalInput = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey),
  sequence: 0xffffffff
};

// Sequence for RBF (Replace-By-Fee)
const rbfInput = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey),
  sequence: 0xfffffffe // Signals RBF enabled
};

// Relative time lock (BIP 68)
// Lock for 144 blocks (approximately 1 day)
const relativeTimeLockBlocks = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey),
  sequence: 144 // Number of blocks
};

// Relative time lock in seconds (512 second intervals)
// Lock for approximately 1 day (169 * 512 seconds)
const relativeTimeLockSeconds = {
  sourceTransaction,
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey),
  sequence: (1 << 22) | 169 // Type flag + time units
};

const tx = new Transaction();
tx.addInput(finalInput);

console.log('Input sequence:', tx.inputs[0].sequence);

4. SPV with Merkle Proofs

Include merkle proofs for SPV validation:

import { Transaction, MerklePath, TransactionInput } from '@bsv/sdk';

// Parse merkle path from network
const merklePath = MerklePath.fromHex('fed7c509000a02fddd01...');

// Attach merkle proof to source transaction
const sourceTransaction = Transaction.fromHex('0100000001...');
sourceTransaction.merklePath = merklePath;

// Create input with SPV proof
const spvInput: TransactionInput = {
  sourceTransaction, // Includes merkle proof
  sourceOutputIndex: 0,
  unlockingScriptTemplate: new P2PKH().unlock(privKey)
};

// The transaction can now be verified with SPV
const tx = new Transaction();
tx.addInput(spvInput);

// Verify merkle proof
const isValidProof = sourceTransaction.merklePath.verify(
  sourceTransaction.id('hex'),
  chainTracker // ChainTracker instance
);

console.log('SPV proof valid:', isValidProof);

// Transaction with SPV proof can be serialized for transmission
const txWithProof = tx.toHex();

// Or use BEEF format for efficient transmission
import { Beef } from '@bsv/sdk';
const beef = new Beef();
beef.addTransaction(tx);
beef.addTransaction(sourceTransaction);
beef.addMerklePath(merklePath);

const beefHex = beef.toHex();
console.log('BEEF transaction package:', beefHex);

API Reference