BSV.Tokens.Factory.Stas3.WitnessBuilder (bsv_sdk v2.0.0)

Copy Markdown View Source

Build a BSV.Tokens.Stas3UnlockWitness (spec §7 slots 1-20) for a single STAS 3.0 input that the factory layer is about to sign.

The factory walks the partially-built transaction and asks this module to derive the witness for each STAS 3.0 input. The witness is then attached to the unlock template via BSV.Tokens.Template.Stas3.with_witness/2 so that Stas3Template.sign/3 produces an unlocking script of the form witness_bytes ‖ authz_bytes.

Slot derivation rules

  • Slots 1-12 (stas_outputs): walk tx.outputs in order, take the first four whose script type is :stas3. Reject if more than 4 are present. For each, extract %{amount, owner_pkh, var2} from the parsed Stas3Fields. var2 is the raw action_data_raw push payload.
  • Slots 13-14 (change): the first non-STAS output whose script type is :p2pkh or :p2mpkh. If absent, leave change = nil.
  • Slot 15 (note_data): the trailing OP_RETURN output's payload. Absent → nil.
  • Slots 16-17 (funding_input): identified by funding_input_index if provided, else the first non-STAS input. Stores txid and vout.
  • Slot 18 (tx_type): caller-supplied (atom or 0..7 byte).
  • Slot 19 (sighash_preimage): BIP-143 preimage for this input as computed via BSV.Transaction.Sighash.calc_preimage/5.
  • Slot 20 (spend_type): caller-supplied (atom or 1..4 byte).

Summary

Types

spend_type()

STAS 3.0 spend type used in slot 20.

tx_type()

STAS 3.0 tx type used in slot 18 — atom form or wire byte.

Functions

derive_witness_for_input(tx, input_index, funding_input_index, spend_type, tx_type, sighash_flag)

Derive a Stas3UnlockWitness for the input at input_index in tx.

Types

spend_type()

@type spend_type() ::
  :transfer | :freeze_unfreeze | :confiscation | :swap_cancellation

STAS 3.0 spend type used in slot 20.

tx_type()

@type tx_type() :: atom() | 0..7

STAS 3.0 tx type used in slot 18 — atom form or wire byte.

Functions

derive_witness_for_input(tx, input_index, funding_input_index, spend_type, tx_type, sighash_flag)

@spec derive_witness_for_input(
  BSV.Transaction.t(),
  non_neg_integer(),
  nil | non_neg_integer(),
  spend_type(),
  tx_type(),
  non_neg_integer()
) :: {:ok, BSV.Tokens.Stas3UnlockWitness.t()} | {:error, term()}

Derive a Stas3UnlockWitness for the input at input_index in tx.

Returns {:ok, witness} or {:error, reason}.

Reasons:

  • {:too_many_stas_outputs, n} — more than 4 STAS outputs in tx, which the spec §7 witness cannot represent.
  • :input_index_out_of_range
  • :missing_source_output — the input has no source_output set.
  • any error returned by BSV.Transaction.Sighash.calc_preimage/5.