types

type Ancestry struct {
	// TreePath is the extracted commitment-tree path from the batch root
	// down to the input VTXO leaf served by this fragment.
	TreePath *tree.Tree

	// CommitmentTxID is the txid of the commitment tx anchoring this
	// fragment. Multiple entries within one Descriptor may share a
	// commitment txid (different leaves of the same commitment tree),
	// but no two entries may carry the same (CommitmentTxID, TreePath)
	// pair.
	CommitmentTxID chainhash.Hash

	// InputIndices lists the Ark tx input indices (within the OOR Ark tx
	// that produced the VTXO) that this fragment serves. Empty for
	// round-direct VTXOs (which are not produced by an OOR Ark tx).
	InputIndices []uint32

	// TreeDepth is the depth of the served leaf within this fragment's
	// tree. Worst-case unilateral-exit timing for the produced VTXO is
	// max(TreeDepth) across all entries.
	TreeDepth uint32

	// CommitmentHeight is the on-chain confirmation height of the
	// commitment tx anchoring this fragment. Zero means unknown (legacy
	// persisted VTXOs, or an unconfirmed/not-yet-resolved commitment), in
	// which case callers fall back to a bounded lookback floor rather than
	// trusting this value.
	CommitmentHeight int32
}

type BatchOutputInfo struct {
	// Idx is the index of this batch output in the batch transaction.
	Idx int

	// SignerKey is they key that the operator will use for the Musig2
	// signing sessions for this batch output.
	SignerKey *btcec.PublicKey

	// Tree is the VTXO tree for this batch output. The tree embeds the
	// per-round sweep key, sweep delay, and PrevOut.
	Tree *tree.Tree
}

type BoardingInputSignature struct {
	// InputIndex is the index of the input in the transaction
	InputIndex int

	// Outpoint identifies which boarding input this signature is for
	Outpoint wire.OutPoint

	// ClientSignature is the client's schnorr signature
	ClientSignature *schnorr.Signature
}

type BoardingRequest struct {
	// Outpoint represents the UTXO that will be used as input to the batch
	// transaction.
	Outpoint *wire.OutPoint

	// PolicyTemplate is the semantic arkscript policy for the boarding
	// output. This is the authoritative join-round representation.
	PolicyTemplate []byte

	// ClientKey is the public key used for the client in the boarding
	// tapscripts.
	ClientKey *btcec.PublicKey

	// OperatorKey is the public key used for the operator in the boarding
	// tapscript collaborative spend path.
	OperatorKey *btcec.PublicKey

	// ExitDelay is the CSV delay used in the unilateral timeout script
	// path of the boarding output. This must be at least the operator's
	// minimum boarding exit delay.
	ExitDelay uint32

	// TxProof is the SPV proof that the boarding UTXO exists in a
	// confirmed block. This allows the server to verify the UTXO without
	// querying its own chain source. The proof includes the transaction,
	// block header, merkle proof, and the taproot output construction
	// details (internal key and merkle root).
	//
	// None means "rely on the server's chain source." This is acceptable
	// when the operator runs a full bitcoind / btcd. Under standalone
	// (lwwallet) deployments the server has no chain source and rejects
	// join requests carrying TxProof=None with "TxProof is required when
	// server has no chain source". Clients SHOULD always populate this
	// field when they can; the wallet's first-confirmation pipeline
	// builds it inline (see wallet.processUtxo) and the
	// maybeRebuildBoardingProof recovery path reconstructs it from the
	// chain backend for any persisted intent that lacks one.
	TxProof fn.Option[proof.TxProof]
}

type ClientBatchInfo struct {
	// Transaction is the batch transaction.
	Transaction *wire.MsgTx

	// BatchOutputs contains the batch output info for each batch output
	// that is relevant to the client. The number of VTXO leaves should
	// match the number of VTXO requests made by the client.
	BatchOutputs []*BatchOutputInfo

	// ConnectorLeafMap maps each forfeited VTXO outpoint to its assigned
	// connector leaf information. This allows the client to determine which
	// connector leaf corresponds to each of their forfeit requests.
	ConnectorLeafMap map[wire.OutPoint]*ConnectorLeafInfo
}

type ConnectorLeafInfo struct {
	// LeafOutpoint is the outpoint of the connector leaf that the forfeit
	// transaction should spend. This is the actual outpoint from the leaf
	// transaction in the connector tree.
	LeafOutpoint wire.OutPoint

	// LeafOutput is the transaction output for the connector leaf. This
	// contains the value and pkScript needed to construct the forfeit
	// transaction witness.
	LeafOutput *wire.TxOut

	// RootOutputIndex is the commitment-tx output index that this
	// connector tree's root transaction spends. It lets the client bind
	// the connector tree to the commitment tx it is about to sign into.
	RootOutputIndex uint32

	// NumLeaves is the total number of connector leaves in the tree this
	// leaf belongs to. Connector trees have identical leaves, so this plus
	// the radix and operator key fully determine the tree shape.
	NumLeaves uint32

	// Radix is the branching factor used to build the connector tree. It
	// is not derivable from the commitment tx, so the operator must supply
	// it for deterministic reconstruction.
	Radix uint32

	// LeafIndex is the position of this leaf within the connector tree's
	// flattened leaf list. Zero is a valid index.
	LeafIndex uint32
}

type ForfeitParticipantSig struct {
	// PubKey is the x-only key that produced Signature.
	PubKey *btcec.PublicKey

	// Signature authorizes the forfeit transaction under PubKey.
	Signature *schnorr.Signature
}

type ForfeitRequest struct {
	// VTXOOutpoint is the outpoint of the VTXO to forfeit.
	VTXOOutpoint *wire.OutPoint

	// Amount is the local value of the forfeited VTXO in satoshis. This
	// is used by the client when validating a round before registration.
	// It is not part of the join-round wire encoding, where the outpoint
	// remains the source of truth.
	Amount btcutil.Amount

	// AuthSpend is the unilateral proof/auth spend path used for join-auth
	// when settling a custom-script output into a round. Standard wallet
	// VTXOs leave this nil and let the operator load the canonical
	// path from the VTXO registry. Custom VTXOs serialize it onto the
	// join-round wire so the operator can validate the caller-provided
	// path.
	AuthSpend *arkscript.SpendPath

	// ForfeitSpend is the operator-backed spend path used locally
	// to build the actual round forfeit transaction for a
	// custom-script output. Standard wallet VTXOs leave this nil and
	// let the operator derive the path from the registered VTXO
	// descriptor. Custom
	// VTXOs serialize it onto the join-round wire so the operator can build
	// the exact connector-bound forfeit request later.
	ForfeitSpend *arkscript.SpendPath
}

type ForfeitTxSig struct {
	// UnsignedTx is the forfeit transaction without any witness data
	UnsignedTx *wire.MsgTx

	// ClientVTXOSig is the client's schnorr signature for the VTXO input
	ClientVTXOSig *schnorr.Signature

	// ParticipantVTXOSigs carries tapscript signatures from all
	// non-operator participants that must authorize the selected
	// spend path. Standard VTXO forfeits need only ClientVTXOSig;
	// custom policies such as vHTLC refund-style paths may require
	// multiple client-side signatures for one forfeited VTXO.
	ParticipantVTXOSigs []*ForfeitParticipantSig

	// SpendPath is the canonical arkscript spend path for the
	// forfeited VTXO input. This makes the custom or standard
	// tapscript leaf an explicit part of round messaging instead
	// of implicit witness metadata.
	SpendPath *arkscript.SpendPath
}

type JoinRoundAuth struct {
	// Message is the canonical join message signed by the client.
	Message []byte

	// ValidFrom is the first block height where this auth intent is
	// accepted.
	ValidFrom uint32

	// ValidUntil is the last block height where this auth intent is
	// accepted. A value of 0 means no upper bound.
	ValidUntil uint32

	// Signature is the serialized full-format BIP-322 signature
	// payload.
	Signature []byte
}

type JoinRoundRequest struct {
	// Identifier is the participant's public key identifier associated with
	// this request.
	Identifier *btcec.PublicKey

	// VTXOReqs specifies the new VTXOs the client wants to receive.
	VTXOReqs []*VTXORequest

	// BoardingReqs specifies the boarding UTXOs the client wants to use
	// to board the Ark.
	BoardingReqs []*BoardingRequest

	// LeaveReqs specifies the requests to leave the Ark with on-chain
	// UTXOs.
	LeaveReqs []*LeaveRequest

	// ForfeitReqs specifies the requests to forfeit VTXOs.
	ForfeitReqs []*ForfeitRequest

	// Auth contains the BIP-322 payload that authorizes this join
	// request.
	Auth *JoinRoundAuth
}

type LeaveRequest struct {
	// Output is the output that will be created to return funds to the
	// client when leaving the Ark. Its Value is the client's target
	// amount; server-filled when IsChange=true.
	Output *wire.TxOut

	// IsChange marks this LeaveRequest as the client's designated
	// fee-bearing change output for the intent.
	IsChange bool
}

type OORPackageDirection int32

type OORPackageLinkKind int32

type OperatorTerms struct {
	// PubKey is the operator's main public key. This should be used for
	// constructing boarding scripts.
	PubKey *btcec.PublicKey

	// BoardingExitDelay is the minimum CSV delay to use for boarding
	// outputs that the operator expects.
	BoardingExitDelay uint32

	// VTXOExitDelay is the minimum CSV delay to use for VTXO outputs. This
	// delay will give the server time to respond to unilateral spends of
	// a VTXO that has been forfeit or spent.
	VTXOExitDelay uint32

	// DustLimit enforces minimum output value for boarding/funding flows.
	DustLimit btcutil.Amount

	// MinVTXOAmount is the operator-advertised minimum VTXO output
	// amount.
	MinVTXOAmount btcutil.Amount

	// MinBoardingAmount is the minimum amount clients must contribute.
	MinBoardingAmount btcutil.Amount

	// MaxVTXOAmount caps the amount accepted per VTXO (optional). The
	// operator applies the same cap to boarding requests, round outputs
	// and OOR recipient outputs.
	MaxVTXOAmount btcutil.Amount

	// MaxUserBalance caps the total balance a single user should hold
	// in the system (optional). The cap is enforced client-side on
	// receive and boarding flows before funds enter the system. Zero
	// means no cap.
	MaxUserBalance btcutil.Amount

	// FeeRate reflects the operator's target package feerate (sat/vByte).
	FeeRate btcutil.Amount

	// MinOperatorFee is the minimum fee (satoshis) the operator
	// requires per join request. The fee is the difference between
	// total input value and total output value.
	MinOperatorFee btcutil.Amount

	// FreeRefreshWindowBlocks is the number of blocks before batch expiry
	// in which a pure refresh qualifies for a complete fee waiver. Zero
	// disables the policy.
	FreeRefreshWindowBlocks uint32

	// MinConfirmations is the minimum confs required on boarding inputs.
	MinConfirmations uint32

	// MaxOORLineageVBytes is the operator-published cap on the
	// cumulative on-chain virtual bytes a recipient must publish to
	// claim a VTXO produced by an OOR submit unilaterally. Clients
	// mirror this cap when selecting OOR inputs so a submit that the
	// operator would reject is rejected pre-network. Zero means the
	// operator does not enforce a cap (the client should fall back to
	// its own conservative default before submitting).
	MaxOORLineageVBytes uint32
}

type VTXOOrigin uint8

type VTXORequest struct {
	// Amount is the client's target amount in satoshis for this
	// output. Server-filled on the responding JoinRoundQuote when
	// IsChange=true.
	Amount btcutil.Amount

	// IsChange marks this request as the intent's designated
	// fee-bearing change output.
	IsChange bool

	// FixedAmount requires the operator quote to preserve Amount exactly.
	// It is used for contract outputs where shrinking the replacement
	// output would invalidate the higher-level protocol. A fixed single
	// output is not eligible for the implicit-change exception.
	FixedAmount bool

	// PolicyTemplate is the semantic arkscript policy for the requested
	// output. This is the authoritative join-round representation.
	PolicyTemplate []byte

	// PkScript is the output script of the VTXO. This will have
	// both a collaborative and unilateral spend path.
	PkScript []byte

	// Expiry is the CSV delay used in the unilateral timeout script path
	// of the VTXO.
	Expiry uint32

	// ClientKey is the public key of the client used in the construction
	// of the collaborative spend path of the VTXO.
	ClientKey *btcec.PublicKey

	// OwnerKey is the local key descriptor for the VTXO owner when this
	// client controls the resulting output. This is local-only
	// metadata and is not serialized onto the join-round wire.
	OwnerKey keychain.KeyDescriptor

	// OperatorKey is the public key of the operator used in the
	// construction of the collaborative spend path of the VTXO.
	OperatorKey *btcec.PublicKey

	// SigningKey is the key descriptor that the client will use in the
	// building of the VTXO tree during Musig2 signing sessions. We use
	// keychain.KeyDescriptor instead of just *btcec.PublicKey because we
	// need the key locator for signing operations.
	SigningKey keychain.KeyDescriptor

	// Origin classifies how a locally-owned VTXO came into
	// existence (boarding, refresh, or participant transfer). It
	// is set by the wallet at intent-composition time and flows
	// through the FSM so the round actor can emit a correctly-
	// typed VTXOReceivedMsg to the ledger actor. Local-only;
	// never serialized over the wire.
	Origin VTXOOrigin
}