STAS transaction factories.
Pure functions that build complete, signed transactions for STAS token operations: issue, transfer, split, merge, redeem, freeze, unfreeze, confiscation, and swap.
v2 Functions (Legacy)
Functions without a v3_ prefix use the legacy STAS v2 template (P2PKH-only,
splittable flag). These are retained for backward compatibility.
v3 Functions
Functions prefixed with v3_ use the new script template with full protocol
support: P2MPKH ownership, 2nd variable field, flags (freezable/confiscatable),
service fields, spending types, and per-transaction note outputs.
Summary
Functions
Build an issue transaction.
Build a merge transaction.
Build a redeem (burn) transaction.
Build a split transaction.
Build a transfer transaction.
Build a v3 STAS base transaction.
Build a v3 STAS confiscation transaction.
Build a v3 STAS freeze transaction.
Build a v3 STAS merge transaction.
Build a v3 STAS split transaction.
Build a v3 STAS swap cancellation transaction.
Build a v3 STAS swap transaction.
Build a v3 STAS transfer transaction (spending type 1).
Build a v3 STAS unfreeze transaction.
Types
@type issue_config() :: %{ contract_utxo: BSV.Tokens.Payment.t(), destinations: [BSV.Tokens.Destination.t()], redemption_pkh: <<_::160>>, splittable: boolean(), funding: BSV.Tokens.Payment.t(), fee_rate: non_neg_integer() }
@type merge_config() :: %{ token_utxos: [BSV.Tokens.Payment.t()], destination: BSV.Tokens.Destination.t(), redemption_pkh: <<_::160>>, splittable: boolean(), funding: BSV.Tokens.Payment.t(), fee_rate: non_neg_integer() }
@type redeem_config() :: %{ token_utxo: BSV.Tokens.Payment.t(), funding: BSV.Tokens.Payment.t(), fee_rate: non_neg_integer() }
@type split_config() :: %{ token_utxo: BSV.Tokens.Payment.t(), destinations: [BSV.Tokens.Destination.t()], redemption_pkh: <<_::160>>, funding: BSV.Tokens.Payment.t(), fee_rate: non_neg_integer() }
@type transfer_config() :: %{ token_utxo: BSV.Tokens.Payment.t(), destination: BSV.Tokens.Destination.t(), redemption_pkh: <<_::160>>, splittable: boolean(), funding: BSV.Tokens.Payment.t(), fee_rate: non_neg_integer() }
@type v3_base_config() :: %{ token_inputs: [BSV.Tokens.TokenInput.t()], fee_txid: binary(), fee_vout: non_neg_integer(), fee_satoshis: non_neg_integer(), fee_locking_script: BSV.Script.t(), fee_private_key: BSV.PrivateKey.t(), destinations: [v3_output_params()], spend_type: BSV.Tokens.SpendType.t(), fee_rate: non_neg_integer(), note_data: binary() | nil }
Config for v3 base spend operations.
@type v3_output_params() :: %{ satoshis: non_neg_integer(), owner_pkh: <<_::160>>, redemption_pkh: <<_::160>>, frozen: boolean(), flags: BSV.Tokens.ScriptFlags.t(), service_fields: [binary()], optional_data: [binary()], action_data: BSV.Tokens.ActionData.t() | nil }
Output parameters for v3 STAS operations.
Same structure as Stas3OutputParams — these are protocol-level fields, not
STAS 3.0-specific.
Functions
@spec build_issue_tx(issue_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build an issue transaction.
@spec build_merge_tx(merge_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a merge transaction.
@spec build_redeem_tx(redeem_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a redeem (burn) transaction.
@spec build_split_tx(split_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a split transaction.
@spec build_transfer_tx(transfer_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a transfer transaction.
@spec build_v3_base_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS base transaction.
This is the core v3 transaction builder. All v3 operations (transfer, split,
merge, freeze, unfreeze, confiscation, swap) route through this function with
appropriate spend_type and destination parameters.
Supports 1–2 token inputs, 1–4 STAS outputs, optional note output, and a fee change output.
@spec build_v3_confiscate_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS confiscation transaction.
Spending type 3. No restrictions on output address, 2nd variable field, or number of outputs. Authorized by the confiscation authority address. Works on frozen and swap-configured UTXOs.
@spec build_v3_freeze_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS freeze transaction.
Sets frozen=true on all destinations. Spending type 2. Requires the token to have the freezable flag set at issuance.
@spec build_v3_merge_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS merge transaction.
Exactly 2 token inputs, 1–2 outputs. Spending type 1.
@spec build_v3_split_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS split transaction.
Exactly 1 token input, 1–4 outputs. Spending type 1.
@spec build_v3_swap_cancel_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS swap cancellation transaction.
Spending type 4. Cancels a standing swap offer by spending the UTXO back to the maker's receive address.
@spec build_v3_swap_flow_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS swap transaction.
Requires exactly 2 token inputs. Spending type 1 for transfer-swap, spending type 4 for swap-swap. Auto-detects based on input scripts.
@spec build_v3_transfer_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS transfer transaction (spending type 1).
@spec build_v3_unfreeze_tx(v3_base_config()) :: {:ok, BSV.Transaction.t()} | {:error, term()}
Build a v3 STAS unfreeze transaction.
Sets frozen=false on all destinations. Spending type 2.