BSV.Tokens.Template.Stas3 (bsv_sdk v1.5.0)

STAS3 unlocking script templates (P2PKH and P2MPKH).

Carries:

signing_key — nil for no-auth, {:single, _} for P2PKH, or

             `{:multi, keys, multisig}` for P2MPKH (§10.2).

spend_type — STAS 3.0 v0.1 §8.2 spendType (1..4).
sighash_flag — sighash type byte (defaults to 0x41 = ALL+FORKID).

no_auth — when true, emit OP_FALSE in place of authz (§10.3).

              The slot-19 sighashPreimage in the §7 witness is
              UNAFFECTED — see `unlock_no_auth/1` for the spec
              author's clarification of the word "preimage" in
              §10.3 (it refers to the address/MPKH preimage in
              the authz slot 21+, not slot 19).

witness — optional BSV.Tokens.Stas3UnlockWitness.t() carrying

              slots 1-20 of the spec §7 witness. When present,
              `sign/3` prepends the witness bytes to the produced
              authz script so the resulting unlocking script is
              `witness ‖ authz`. When absent, the template emits
              only authz (legacy behaviour, kept for backward
              compatibility with callers that build the witness
              themselves or unit-test the authz block in isolation).

Summary

Functions

estimate_length(stas3, _, _)

Estimated unlocking script length in bytes.

sign(tpl, tx, input_index)

Sign a STAS3 input, producing a P2PKH or P2MPKH unlocking script.

unlock(key, spend_type, opts \\ [])

Create a STAS3 unlocker from a private key (P2PKH, backward compatible).

unlock_from_signing_key(signing_key, spend_type, opts \\ [])

Create a STAS3 unlocker from a SigningKey.

unlock_mpkh(private_keys, multisig, spend_type, opts \\ [])

Create a STAS3 P2MPKH unlocker.

unlock_no_auth(spend_type)

Create a STAS3 unlocker that emits no signature (spec §9.5 / §10.3).

with_witness(tpl, witness)

Attach a Stas3UnlockWitness (§7 slots 1-20) to an existing template.

Types

t()

@type t() :: %BSV.Tokens.Template.Stas3{
  no_auth: boolean(),
  sighash_flag: non_neg_integer(),
  signing_key: BSV.Tokens.SigningKey.t() | nil,
  spend_type: BSV.Tokens.Stas3SpendType.t(),
  witness: BSV.Tokens.Stas3UnlockWitness.t() | nil
}

Functions

estimate_length(stas3, _, _)

Estimated unlocking script length in bytes.

sign(tpl, tx, input_index)

Sign a STAS3 input, producing a P2PKH or P2MPKH unlocking script.

unlock(key, spend_type, opts \\ [])

@spec unlock(BSV.PrivateKey.t(), BSV.Tokens.Stas3SpendType.t(), keyword()) :: t()

Create a STAS3 unlocker from a private key (P2PKH, backward compatible).

unlock_from_signing_key(signing_key, spend_type, opts \\ [])

@spec unlock_from_signing_key(
  BSV.Tokens.SigningKey.t(),
  BSV.Tokens.Stas3SpendType.t(),
  keyword()
) ::
  t()

Create a STAS3 unlocker from a SigningKey.

unlock_mpkh(private_keys, multisig, spend_type, opts \\ [])

@spec unlock_mpkh(
  [BSV.PrivateKey.t()],
  BSV.Transaction.P2MPKH.multisig_script(),
  BSV.Tokens.Stas3SpendType.t(),
  keyword()
) :: t()

Create a STAS3 P2MPKH unlocker.

unlock_no_auth(spend_type)

@spec unlock_no_auth(BSV.Tokens.Stas3SpendType.t()) :: t()

Create a STAS3 unlocker that emits no signature (spec §9.5 / §10.3).

When the input UTXO's owner field equals EMPTY_HASH160 = HASH160(""), the swap engine accepts OP_FALSE in place of both the signature and the address/MPKH preimage (the pubkey for P2PKH or the bare-multisig redeem buffer for P2MPKH whose HASH160 equals owner). The engine skips all ECDSA checks for that party.

Spec author's clarification of the §10.3 word "preimage"

The "preimage" the spec talks about in §10.3 is the address/MPKH preimage — the data living in the authz block (§7 unlock witness slot 21+) whose HASH160 equals the owner field. It is NOT the sighashPreimage (slot 19), which is a BIP-143 transaction preimage used by the engine's preimage-driven outputs/sighash checks and which MUST remain intact even on the no-auth path.

Concretely, when this template is paired with with_witness/2 so the produced unlocking script is witness ‖ authz (the normal STAS 3.0 v0.1 §7 shape), the result is:

slot 19 (sighashPreimage) — the real BIP-143 preimage computed via BSV.Transaction.Sighash.calc_preimage/5, identical to the P2PKH / P2MPKH paths.
slot 21+ (authz) — a single OP_FALSE push (<<0x00>>) in place of <sig> <pubkey> (P2PKH) or OP_0 <sigs> <redeem> (P2MPKH).

Without an attached witness (legacy / unit-test path) the resulting unlocking script is just the bare authz region: a single OP_FALSE push.

with_witness(tpl, witness)

@spec with_witness(t(), BSV.Tokens.Stas3UnlockWitness.t()) :: t()

Attach a Stas3UnlockWitness (§7 slots 1-20) to an existing template.

When the template carries a witness, sign/3 prepends the encoded witness bytes to the produced authz script so the resulting unlocking script is witness ‖ authz per spec §7.