Struct Vtxo 

pub struct Vtxo<G = Full, P = VtxoPolicy> { /* private fields */ }

Represents a VTXO in the Ark.

The correctness of the return values of methods on this type is conditional on the VTXO being valid. For invalid VTXOs, the methods should never panic, but can return incorrect values. It is advised to always validate a VTXO upon receipt using Vtxo::validate.

Be mindful of calling Clone on a Vtxo, as they can be of non-negligible size. It is advised to use references where possible or use an std::rc::Rc or std::sync::Arc if needed.

Implementations of PartialEq, Eq, PartialOrd, Ord and Hash are proxied to the implementation on Vtxo::id.

Implementations

impl<G, P: Policy> Vtxo<G, P>

pub fn id(&self) -> VtxoId

Get the identifier for this Vtxo.

This is the same as Vtxo::point but encoded as a byte array.

pub fn point(&self) -> OutPoint

The outpoint from which to build forfeit or arkoor txs.

This can be an on-chain utxo or an off-chain vtxo.

pub fn amount(&self) -> Amount

The amount of the Vtxo.

pub fn chain_anchor(&self) -> OutPoint

The UTXO that should be confirmed for this Vtxo to be valid.

It is the very root of the VTXO.

pub fn policy(&self) -> &P

The output policy of this VTXO.

pub fn policy_type(&self) -> VtxoPolicyKind

The output policy type of this VTXO.

pub fn expiry_height(&self) -> BlockHeight

The expiry height of the Vtxo.

pub fn server_pubkey(&self) -> PublicKey

The server pubkey used in arkoor transitions.

pub fn exit_delta(&self) -> BlockDelta

The relative timelock block delta used for exits.

pub fn output_taproot(&self) -> TaprootSpendInfo

The taproot spend info for the output of this Vtxo.

pub fn output_script_pubkey(&self) -> ScriptBuf

The scriptPubkey of the output of this Vtxo.

pub fn txout(&self) -> TxOut

The transaction output (eventual UTXO) of this Vtxo.

pub fn to_bare(&self) -> Vtxo<Bare, P>

Convert to a bare VTXO, Vtxo<Bare>

pub fn into_bare(self) -> Vtxo<Bare, P>

Convert into a bare VTXO, Vtxo<Bare>

impl<P: Policy> Vtxo<Bare, P>

pub fn new( point: OutPoint, policy: P, amount: Amount, expiry_height: BlockHeight, server_pubkey: PublicKey, exit_delta: BlockDelta, anchor_point: OutPoint, ) -> Self

Construct a bare VTXO from its individual fields.

pub fn with_genesis( self, genesis: Full, ) -> Result<Vtxo<Full, P>, VtxoValidationError>

Upgrade this bare VTXO to a Vtxo<Full, P> by attaching a previously stripped or decoded genesis chain.

Field-by-field copy mirroring the inverse of Vtxo::into_bare. The VTXO’s point is a deterministic checksum of the genesis chain, so a caller passing a mismatched genesis would simply produce an invalid VTXO; use [Vtxo::with_genesis_checked] when paranoia is warranted.

A VtxoValidationError::MissingGenesisItems will be returned if the provided genesis contains no genesis transitions and the Vtxo::point and Vtxo::chain_anchor are not equal.

No further validation of the VTXO will be performed. It’s recommended to run Vtxo::validate to ensure the VTXO data is consistent with the provided genesis.

impl<P: Policy> Vtxo<Full, P>

pub fn exit_depth(&self) -> u16

Returns the total exit depth (including OOR depth) of the vtxo.

pub fn past_arkoor_pubkeys(&self) -> Vec<Vec<PublicKey>>

Iterate over all oor transitions in this VTXO

The outer Vec cointains one element for each transition. The inner Vec contains all pubkeys within that transition.

This does not include the current arkoor pubkey, for that use Vtxo::arkoor_pubkey.

pub fn has_all_witnesses(&self) -> bool

Whether all transaction witnesses are present

It is possible to represent unsigned or otherwise unfinished VTXOs, for which this method will return false.

pub fn is_standard(&self) -> bool

Check if this VTXO is standard for relay purposes

A VTXO is standard if:

• Its own output is standard
• all sibling outputs in the exit path are standard
• each part of the exit path should have a P2A output

pub fn unlock_hash(&self) -> Option<UnlockHash>

Returns the “hArk” unlock hash if this is a hArk leaf VTXO

pub fn provide_unlock_signature(&mut self, signature: Signature) -> bool

Provide the leaf signature for an unfinalized hArk VTXO

Returns true if this VTXO was an unfinalized hArk VTXO.

pub fn provide_unlock_preimage(&mut self, preimage: UnlockPreimage) -> bool

Provide the unlock preimage for an unfinalized hArk VTXO

Returns true if this VTXO was an unfinalized hArk VTXO and the preimage matched.

pub fn transactions(&self) -> VtxoTxIter<'_, P>

Iterator that constructs all the exit txs for this Vtxo.

pub fn encode_genesis<W: Write + ?Sized>(&self, w: &mut W) -> Result<(), Error>

Encode just the genesis chain.

The wire format is the same as the genesis section embedded inside a full VTXO encoding at [VTXO_ENCODING_VERSION], so callers that already store a Vtxo alongside this blob can reassemble the full VTXO via [Vtxo::::decode_genesis] and Vtxo::with_genesis.

pub fn deserialize_with_genesis( vtxo_bytes: &[u8], genesis_bytes: &[u8], ) -> Result<Self, ProtocolDecodingError>

where P: ProtocolEncoding,

Similar to Vtxo::deserialize but it takes two byte splices, one containing Vtxo<Bare> data and one for the Full genesis data.

pub fn serialize_genesis(&self) -> Vec<u8>

Serialize the genesis chain into a fresh Vec<u8>.

pub fn validate( &self, chain_anchor_tx: &Transaction, ) -> Result<(), VtxoValidationError>

Fully validate this VTXO and its entire transaction chain.

The chain_anchor_tx must be the tx with txid matching Vtxo::chain_anchor.

pub fn validate_unsigned( &self, chain_anchor_tx: &Transaction, ) -> Result<(), VtxoValidationError>

Validate VTXO structure without checking signatures.

impl<G> Vtxo<G, VtxoPolicy>

pub fn user_pubkey(&self) -> PublicKey

Returns the user pubkey associated with this Vtxo.

pub fn arkoor_pubkey(&self) -> Option<PublicKey>

The public key used to cosign arkoor txs spending this Vtxo. This will return None if VtxoPolicy::is_arkoor_compatible returns false for this VTXO’s policy.

impl<G> Vtxo<G, ServerVtxoPolicy>

pub fn try_into_user_vtxo(self) -> Result<Vtxo<G, VtxoPolicy>, ServerVtxo<G>>

Try to convert into a user Vtxo

Returns the original value on failure.

Trait Implementations

impl<G, P: Policy> AsRef<Vtxo<G, P>> for Vtxo<G, P>

fn as_ref(&self) -> &Vtxo<G, P>

Converts this type into a shared reference of the (usually inferred) input type.

impl<G: Clone, P: Clone> Clone for Vtxo<G, P>

fn clone(&self) -> Vtxo<G, P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<G: Debug, P: Debug> Debug for Vtxo<G, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<RawVtxo> for Vtxo<Full, ServerVtxoPolicy>

fn from(r: RawVtxo) -> Self

Converts to this type from the input type.

impl From<Vtxo<Full, ServerVtxoPolicy>> for RawVtxo

fn from(v: Vtxo<Full, ServerVtxoPolicy>) -> Self

Converts to this type from the input type.

impl<G> From<Vtxo<G>> for ServerVtxo<G>

fn from(vtxo: Vtxo<G>) -> ServerVtxo<G>

Converts to this type from the input type.

impl<G, P: Policy> Hash for Vtxo<G, P>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<G, P: Policy> Ord for Vtxo<G, P>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<G, P: Policy> PartialEq for Vtxo<G, P>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<G, P: Policy> PartialOrd for Vtxo<G, P>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<P: Policy + ProtocolEncoding> ProtocolEncoding for Vtxo<Bare, P>

fn encode<W: Write + ?Sized>(&self, w: &mut W) -> Result<(), Error>

Encode the object into the writer.

fn decode<R: Read + ?Sized>(r: &mut R) -> Result<Self, ProtocolDecodingError>

Decode the object from the writer.

fn serialize(&self) -> Vec<u8>

Serialize the object into a byte vector.

fn deserialize(byte_slice: &[u8]) -> Result<Self, ProtocolDecodingError>

Deserialize object from the given byte slice.

fn serialize_hex(&self) -> String

Serialize the object to a lowercase hex string.

fn deserialize_hex(hex_str: &str) -> Result<Self, ProtocolDecodingError>

Deserialize object from hex slice.

impl<P: Policy + ProtocolEncoding> ProtocolEncoding for Vtxo<Full, P>

fn encode<W: Write + ?Sized>(&self, w: &mut W) -> Result<(), Error>

Encode the object into the writer.

fn decode<R: Read + ?Sized>(r: &mut R) -> Result<Self, ProtocolDecodingError>

Decode the object from the writer.

fn serialize(&self) -> Vec<u8>

Serialize the object into a byte vector.

fn deserialize(byte_slice: &[u8]) -> Result<Self, ProtocolDecodingError>

Deserialize object from the given byte slice.

fn serialize_hex(&self) -> String

Serialize the object to a lowercase hex string.

fn deserialize_hex(hex_str: &str) -> Result<Self, ProtocolDecodingError>

Deserialize object from hex slice.

impl<'a, P: Policy> VtxoRef<P> for &'a Vtxo<Bare, P>

fn vtxo_id(&self) -> VtxoId

The VtxoId of the VTXO

fn as_bare_vtxo(&self) -> Option<Cow<'_, Vtxo<Bare, P>>>

If the bare Vtxo can be provided, provides it by reference

fn into_full_vtxo(self) -> Option<Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by value, either directly or via cloning

fn as_full_vtxo(&self) -> Option<&Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by reference

impl<'a, P: Policy> VtxoRef<P> for &'a Vtxo<Full, P>

fn vtxo_id(&self) -> VtxoId

The VtxoId of the VTXO

fn as_bare_vtxo(&self) -> Option<Cow<'_, Vtxo<Bare, P>>>

If the bare Vtxo can be provided, provides it by reference

fn as_full_vtxo(&self) -> Option<&Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by reference

fn into_full_vtxo(self) -> Option<Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by value, either directly or via cloning

impl<P: Policy> VtxoRef<P> for Vtxo<Bare, P>

fn vtxo_id(&self) -> VtxoId

The VtxoId of the VTXO

fn as_bare_vtxo(&self) -> Option<Cow<'_, Vtxo<Bare, P>>>

If the bare Vtxo can be provided, provides it by reference

fn into_full_vtxo(self) -> Option<Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by value, either directly or via cloning

fn as_full_vtxo(&self) -> Option<&Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by reference

impl<P: Policy> VtxoRef<P> for Vtxo<Full, P>

fn vtxo_id(&self) -> VtxoId

The VtxoId of the VTXO

fn as_bare_vtxo(&self) -> Option<Cow<'_, Vtxo<Bare, P>>>

If the bare Vtxo can be provided, provides it by reference

fn as_full_vtxo(&self) -> Option<&Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by reference

fn into_full_vtxo(self) -> Option<Vtxo<Full, P>>

If the full Vtxo can be provided, provides it by value, either directly or via cloning

impl<G, P: Policy> Eq for Vtxo<G, P>