subtx-generator

Part of the BSV Layered Multicast open-source project; see the main repository for the full architecture, design docs, and BRC specifications.

Random BSV-over-UDP frame generator for load and functional testing of shard-proxy and shard-listener.

Supports v1 (44-byte header) and BRC-124/v2 (92-byte header, with HashKey, SeqNum, SubtreeID) frame formats and is designed for multi-core line-rate emission. Note: HashKey and SeqNum are emitted as zero; the proxy stamps them in-place before multicast forwarding.

Features

• Random BSV-shaped tx payloads: shape-correct (version / vin / vout / locktime), seeded per worker, no shared PRNG contention.
• Subtree ID pool: N deterministic 32-byte IDs derived from a user seed. Same seed ⇒ same IDs across runs, machines, and test scenarios.
• Sequence numbers: shared atomic allocator with optional gap injection (permanent or delayed retransmission) to drive listener-side NACK / retry tests.
• Multi-core sender: one UDP conn per worker, lock-free hot path, ticker-paced emission (smooth at ≤ 1 kpps, millisecond bursts above).
• Deterministic Subtree pick: SubtreeID = pool[uint64(TxID[:8]) % N] so listeners filtering on a single subtree see a predictable traffic fraction (≈ 1/N).
• Consumer tunnel sink: tunnel-sink receives and logs the tunnel delivery lanes (tx / BRC-143 subtree / BRC-144 block) with per-object diagnostic lines and exit-time summary statistics; optional submit relay logs the sent direction too.
• Unified structured logging: uses shard-common/logging; set LOG_FORMAT=json for JSON-on-stdout matching the rest of the fleet. See Unified Component Logging.

Install

go install github.com/lightwebinc/subtx-generator/cmd/subtx-gen@latest

Or local build:

make build           # builds every cmd/* binary into the repo root

Quick start

subtx-gen \
  -addr [fd20::2]:8725 \
  -frame-version 2 \
  -shard-bits 2 \
  -subtrees 8 \
  -subtree-seed 'example-seed' \
  -pps 1000 \
  -duration 10s

Direct-multicast mode, gap injection, BRC-127 announce (incl. phased mode), tunnel-sink, and scripts/exercise-lanes.sh examples are in docs/usage.md.

Layout

cmd/subtx-gen/            CLI entry point (BRC-124/128 frame generator)
cmd/send-block-announce/  BRC-131 block announce sender (TCP, legacy)
cmd/send-subtree-data/    BRC-132 subtree data sender (TCP, legacy)
cmd/send-anchor-frame/    BRC-134 anchor transaction sender (UDP default, -tcp opt)
cmd/send-subtree-push/    BRC-143 subtree push sender (TCP, lane 8726)
cmd/send-block-push/      BRC-144 block push sender (TCP, lane 8727)
cmd/tunnel-sink/          consumer tunnel delivery sink + submit relay (diagnostic logger)
scripts/exercise-lanes.sh drive tx + subtree + block lanes at one edge concurrently
internal/tx/              exact-size walkable tx payload builder (raw + BRC-30 EF; never pads)
internal/subtree/         deterministic subtree-ID pool
internal/seq/             shared seq allocator + gap injector
internal/frame/           v1/v2 encoder wrapper around shard-common
internal/rate/            ticker-based pacer (smooth / burst)
internal/sender/          worker pool driving net.UDPConn per worker
internal/announce/        BRC-127 SubtreeGroupAnnounce TCP sender
internal/blockhdr/        synthetic PoW-valid 80-byte block-header builder

send-block-announce and send-subtree-data are legacy privileged senders; see Miner port deprecation.

Documentation

• Usage: worked examples for every binary
• Configuration: every flag
• Architecture: pipeline position, frame generation, package structure

Container image

Images are published per release tag as ghcr.io/lightwebinc/subtx-generator:<tag> (current 0.4.0): one gcr.io/distroless/static:nonroot image with all seven binaries and no ENTRYPOINT, so the caller picks the binary. See docs/usage.md § Container image.

Helm chart

A Kubernetes Helm chart is published from a dedicated chart repository:

• Repository: charts/subtx-generator
• Install: helm install subtx-generator oci://ghcr.io/lightwebinc/charts/subtx-generator

The chart packages a single multi-binary image and selects which binary to run via .Values.mode (see the chart README for the mode list). Because these binaries accept CLI flags only (no env vars), the chart renders the matching per-mode args block into the container's command + args. Both Deployment and Job workload types are supported. See the chart README for the full reference.

Releases

Releases and release notes live on GitHub Releases; there is no CHANGELOG.

License

Apache 2.0. See LICENSE and NOTICE.