@spec build_stas3_flags(boolean() | BSV.Tokens.ScriptFlags.t()) :: binary()

Build flags byte from boolean options.

Accepts either a single boolean (legacy: freezable only) or a ScriptFlags struct for full flag support.

@spec build_stas3_locking_script(
  <<_::160>>,
  <<_::160>>,
  BSV.Tokens.ActionData.t() | nil,
  boolean(),
  boolean() | BSV.Tokens.ScriptFlags.t(),
  [binary()],
  [binary()]
) :: {:ok, BSV.Script.t()} | {:error, term()}

Build a STAS3 locking script.

Parameters

• owner_pkh - 20-byte owner public key hash
• redemption_pkh - 20-byte redemption public key hash
• action_data - optional action data ({:swap, hash} or {:custom, bytes})
• frozen - whether the token is frozen
• freezable - whether the token supports freeze operations
• service_fields - list of additional service field binaries
• optional_data - list of additional optional data binaries

@spec compute_stas3_requested_script_hash(binary()) :: <<_::256>>

Compute the requestedScriptHash for a STAS3 locking script.

Extracts the "tail" of a locking script (everything after the owner and action_data fields), then returns SHA256(tail). This hash is used in swap action data to identify the counterparty's expected locking script structure.

Parameters

• locking_script - Full STAS3 locking script binary

Returns

A 32-byte SHA256 hash of the locking script tail.

@spec decode_swap_action_data(binary()) ::
  {:ok, BSV.Tokens.ActionData.swap_fields()} | {:error, term()}

Decode a swap action data binary into structured fields.

Parses one or more 61-byte swap legs from the binary. Each leg starts with kind byte 0x01 followed by 32-byte hash, 20-byte PKH, and two uint32 LE values.

Parameters

• data - Binary starting with kind byte 0x01

Returns

{:ok, swap_fields} or {:error, reason}

@spec encode_swap_action_data(BSV.Tokens.ActionData.swap_fields()) :: binary()

Encode swap action data fields into a binary for embedding in a locking script.

Each swap leg is 61 bytes: 1 (kind 0x01) + 32 (hash) + 20 (pkh) + 4 (numerator LE) + 4 (denominator LE).

Parameters

• fields - Map with :requested_script_hash (32 bytes), :requested_pkh (20 bytes), :rate_numerator (uint32), :rate_denominator (uint32)

Returns

A 61-byte binary encoding the swap action data.

@spec extract_stas3_script_tail(binary()) :: binary()

Extract the locking script tail (everything after owner + action_data fields).

The STAS3 locking script layout is:

1. Owner field: OP_DATA_20 (0x14) + 20-byte PKH
2. Action data field: push_data or OP_FALSE(0x00) or OP_2(0x52)
3. Tail: everything from base template to end of script

Parameters

• script - Full STAS3 locking script binary

Returns

Binary containing everything after the action_data field.

@spec push_data(binary()) :: binary()

Push data with appropriate length prefix.