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

Copy Markdown View Source

STAS 3.0 v0.1 §9 build-time enforcement helpers.

These predicates run BEFORE signing, on the resolved input + destination set assembled by a factory. They catch spec violations at construction time so that we never produce a transaction whose engine would reject it on broadcast.

Coverage

  • freeze/2 — §9.2 Freeze / Unfreeze:

    • exactly one STAS output,
    • non-var2 fields byte-identical to the input,
    • FREEZABLE flag bit set in the input's flags.

  • confiscation/1 — §9.3 Confiscation:

    • CONFISCATABLE flag bit set in the input's flags.

  • swap_cancel/2 — §9.4 Swap cancellation:

    • input must carry a swap descriptor (action 0x01),
    • exactly one STAS output,
    • output's owner equals the input's var2.receiveAddr.

Each function returns :ok on success or {:error, atom_or_tuple} on failure. Error atoms are the ones documented in the brief:

  • :freeze_output_count, :freeze_field_drift, :freeze_flag_not_set
  • :confiscate_flag_not_set
  • :swap_cancel_missing_descriptor, :swap_cancel_output_count, :swap_cancel_owner_mismatch

Per spec §9.6, these checks are applied independently — the calling factory chooses which to invoke based on its own intent. The §9.6 precedence rule (Confiscation > Freeze > Swap > Regular) is informative for engines that must classify a spend post-hoc; in this SDK the factory is authoritative.

Summary

Types

destination()

A STAS3 destination as understood by the STAS3 factory layer.

token_input()

A token input as understood by the STAS3 factory layer.

Functions

confiscation(token_input)

Validate a confiscation build per spec §9.3.

freeze(token_input, destinations)

Validate a freeze (or unfreeze) build per spec §9.2.

swap_cancel(token_input, destinations)

Validate a swap-cancellation build per spec §9.4.

Types

destination()

@type destination() :: %{:owner_pkh => <<_::160>>, optional(any()) => any()}

A STAS3 destination as understood by the STAS3 factory layer.

token_input()

@type token_input() :: %{:locking_script => BSV.Script.t(), optional(any()) => any()}

A token input as understood by the STAS3 factory layer.

Functions

confiscation(token_input)

@spec confiscation(token_input()) :: :ok | {:error, atom()}

Validate a confiscation build per spec §9.3.

Requires only that the input's flags field has the CONFISCATABLE bit set. Output count and var2 content are unconstrained per spec.

freeze(token_input, destinations)

@spec freeze(token_input(), [destination()]) :: :ok | {:error, atom()}

Validate a freeze (or unfreeze) build per spec §9.2.

Requires:

  • exactly one destination (single STAS output),
  • destination's owner_pkh and redemption_pkh byte-identical to the input — var2 is the only field permitted to drift,
  • input's flags field has the FREEZABLE bit set.

swap_cancel(token_input, destinations)

@spec swap_cancel(token_input(), [destination()]) :: :ok | {:error, atom()}

Validate a swap-cancellation build per spec §9.4.

Requires:

  • input's var2 parses as a swap descriptor (action 0x01),
  • exactly one destination,
  • destination's owner_pkh equals the input's var2.receiveAddr.

Authorisation against receiveAddr is enforced by the engine at spend time and is not re-checked here.