txgen

package
v0.0.0-...-c0f26df Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package txgen produces signed BSV transactions for the acceptance test suite. The Funder owns wallet state (WIF, derived key, address, UTXO set) and bootstraps via SV Node sendtoaddress. The Builder constructs and signs transactions of any common script shape (P2PKH, P2MS multi-sig, P2SH, OP_RETURN data carrier).

SP4 is unit-tests-only. Live broadcast happens in SP5+ via the teranode and svnode RPC clients.

Index

Constants

View Source
const MinChainDepthFR7 = 25

MinChainDepthFR7 is the acceptance threshold for NEW-FR7: chain depth ≥25 must be constructable without error.

Variables

View Source
var ErrInsufficientFunds = errors.New("txgen: insufficient funds")

ErrInsufficientFunds is returned when the funder does not have enough satoshis to satisfy a BuildRequest at the given fee rate.

View Source
var ErrNoWallet = errors.New("txgen: SV Node wallet not available")

ErrNoWallet is returned when SV Node lacks wallet support and Bootstrap cannot proceed. Tests should skip cleanly when they see this error.

Functions

func ComputeFee

func ComputeFee(sizeBytes int, satPerKB uint64) uint64

ComputeFee returns the fee in satoshis for a given size and rate (sat/kB). Rounds up so we never underpay.

func EstimateSize

func EstimateSize(numInputs int, outputs []Output) int

EstimateSize returns a conservative serialized size in bytes for a transaction with the given P2PKH input count and the given outputs.

func MultisigScript

func MultisigScript(m int, pubkeys [][]byte) ([]byte, error)

MultisigScript returns the bare m-of-n multisig locking script: OP_M <pk1> ... <pkN> OP_N OP_CHECKMULTISIG.

func OpReturnScript

func OpReturnScript(data []byte) ([]byte, error)

OpReturnScript returns OP_FALSE OP_RETURN <push data>.

func P2PKHScript

func P2PKHScript(addr string) ([]byte, error)

P2PKHScript returns the standard pay-to-pubkey-hash locking script for the given Bitcoin address.

func P2SHScript

func P2SHScript(redeemScript []byte) ([]byte, error)

P2SHScript returns OP_HASH160 <hash160(redeem)> OP_EQUAL.

Types

type BuildRequest

type BuildRequest struct {
	Outputs   []Output
	FeeRate   uint64 // sat/kB
	SpendUTXO *UTXO  // optional explicit input
}

BuildRequest specifies what to build.

type BuildResult

type BuildResult struct {
	TxID   [32]byte
	HexTx  string
	Inputs []UTXO
	Change *UTXO // nil if dust-absorbed
}

BuildResult is the outcome of a Build* call.

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder constructs and signs transactions on behalf of a Funder.

func (*Builder) BuildChain

func (b *Builder) BuildChain(req BuildRequest, depth int) ([]BuildResult, error)

BuildChain constructs a chain of `depth` dependent P2PKH transactions: tx[0] spends a starting UTXO; tx[i+1] spends tx[i]'s change output. Each tx pays req.Outputs[0].Satoshis to req.Outputs[0].Script (typically a small dust-above payment to keep the chain alive).

func (*Builder) BuildOpReturn

func (b *Builder) BuildOpReturn(req BuildRequest, dataPayload []byte) (BuildResult, error)

BuildOpReturn constructs a tx whose first output is OP_RETURN data; other outputs (if any) come from req.Outputs.

func (*Builder) BuildP2MS

func (b *Builder) BuildP2MS(req BuildRequest, m int, pubkeys [][]byte, satoshisToMultisig uint64) (BuildResult, error)

BuildP2MS constructs a transaction whose first output is a bare m-of-n multisig output (paying TO the multisig script). Inputs remain P2PKH from the funder.

func (*Builder) BuildP2PKH

func (b *Builder) BuildP2PKH(req BuildRequest) (BuildResult, error)

BuildP2PKH constructs a transaction whose outputs are exactly req.Outputs (the caller already specified scripts), funded by the funder's UTXOs. A change output paying back to the funder's address is appended when the residual exceeds the dust threshold.

If req.SpendUTXO is non-nil, that UTXO is used as the sole input and coin selection is skipped.

func (*Builder) BuildP2SH

func (b *Builder) BuildP2SH(req BuildRequest, redeemScript []byte, satoshisToP2SH uint64) (BuildResult, error)

BuildP2SH constructs a transaction whose first output is a P2SH output committing to redeemScript. The redeemScript itself is not included in the transaction (it's revealed only at spend time).

func (*Builder) BuildSplitter

func (b *Builder) BuildSplitter(n int, satsPerOutput uint64, feeRate uint64) (BuildResult, error)

BuildSplitter constructs a transaction with `n` outputs, each paying `satsPerOutput` to the funder's own address. Used by tests that need many independent UTXOs (INTER-2 needs 1000).

type Funder

type Funder struct {
	// contains filtered or unexported fields
}

Funder holds wallet state for the txgen package.

func NewFunder

func NewFunder(rpc RPCCaller, wifStr string, logger *slog.Logger) (*Funder, error)

NewFunder constructs a Funder. wifStr is the funding wallet's WIF; rpc may be nil if the test will only inject UTXOs directly.

func (*Funder) AddUTXO

func (f *Funder) AddUTXO(u UTXO)

AddUTXO injects a UTXO into the funder. Used by tests and by Confirm/Bootstrap.

func (*Funder) Address

func (f *Funder) Address() string

Address returns the P2PKH address the WIF controls.

func (*Funder) Balance

func (f *Funder) Balance() uint64

Balance returns the sum of all UTXOs the funder currently knows about.

func (*Funder) Bootstrap

func (f *Funder) Bootstrap(ctx context.Context, satoshis uint64) (UTXO, error)

Bootstrap calls SV Node's sendtoaddress RPC to obtain a fresh UTXO of the given size paying to the funder's address, then registers the new UTXO with the funder.

Returns ErrNoWallet (wrapped) when SV Node lacks wallet support so SP5+ tests can skip cleanly.

func (*Funder) Builder

func (f *Funder) Builder() *Builder

Builder returns a Builder backed by the funder.

func (*Funder) Confirm

func (f *Funder) Confirm(spent []UTXO, change *UTXO)

Confirm marks inputs spent and (optionally) adds the change UTXO. Tests call this after a successful broadcast.

func (*Funder) ConfirmMulti

func (f *Funder) ConfirmMulti(spent []UTXO, newOutputs []UTXO)

ConfirmMulti marks `spent` UTXOs as no longer available and registers every UTXO in `newOutputs` as spendable. Used by tests that mine transactions creating multiple outputs (e.g. the INTER-2 splitter).

func (*Funder) MarkSpent

func (f *Funder) MarkSpent(spent []UTXO)

MarkSpent removes the given UTXOs from the funder's set. Used by Confirm after broadcast.

func (*Funder) PrivateKey

func (f *Funder) PrivateKey() *bec.PrivateKey

PrivateKey returns the underlying secp256k1 key. Used by Builder.

func (*Funder) Reset

func (f *Funder) Reset()

Reset clears all UTXOs. For test cleanup only.

func (*Funder) SelectInputs

func (f *Funder) SelectInputs(target uint64, outputs []Output, satPerKB uint64) (inputs []UTXO, fee uint64, change uint64, err error)

SelectInputs picks UTXOs to cover (target + estimated fee) under the greedy first-fit policy. Outputs is the intended output set so the fee can be estimated; SelectInputs assumes the caller will add a change output if necessary.

Returns the chosen inputs, the fee paid, and the change satoshis (zero when change would be dust).

func (*Funder) SnapshotUTXOs

func (f *Funder) SnapshotUTXOs() []UTXO

SnapshotUTXOs returns a copy of the UTXO list under the lock. Used by SelectInputs and tests.

type Output

type Output struct {
	Script      []byte
	Satoshis    uint64
	Description string
}

Output is one output spec for a BuildRequest.

type RPCCaller

type RPCCaller interface {
	Call(ctx context.Context, method string, params []any, out any) error
}

RPCCaller is the minimal interface Funder needs for Bootstrap. In production this is *svnode.RPCClient; tests inject a fake.

type UTXO

type UTXO struct {
	TxID        [32]byte
	Vout        uint32
	Satoshis    uint64
	Script      []byte
	BlockHeight int64 // 0 = unconfirmed
}

UTXO represents one unspent output controlled by the funder.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL