ark/vtxo/policy/

mod.rs

pub mod clause;
pub mod signing;

use std::fmt;
use std::str::FromStr;

use bitcoin::{Amount, ScriptBuf, TxOut, taproot};
use bitcoin::secp256k1::PublicKey;

use bitcoin_ext::{BlockDelta, BlockHeight, TaprootSpendInfoExt};

use crate::{SECP, musig };
use crate::lightning::PaymentHash;
use crate::vtxo::TapScriptClause;
use crate::vtxo::policy::clause::{
	DelayedSignClause, DelayedTimelockSignClause, HashDelaySignClause, TimelockSignClause,
	VtxoClause,
};

/// Type enum of [VtxoPolicy].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum VtxoPolicyKind {
	/// Standard VTXO output protected with a public key.
	Pubkey,
	/// A public policy that grants bitcoin back to the server after expiry
	/// It is used to construct checkpoint transactions
	Checkpoint,
	/// A VTXO that represents an HTLC with the Ark server to send money.
	ServerHtlcSend,
	/// A VTXO that represents an HTLC with the Ark server to receive money.
	ServerHtlcRecv,
}

impl fmt::Display for VtxoPolicyKind {
	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
	    match self {
			Self::Pubkey => f.write_str("pubkey"),
			Self::Checkpoint => f.write_str("checkpoint"),
			Self::ServerHtlcSend => f.write_str("server-htlc-send"),
			Self::ServerHtlcRecv => f.write_str("server-htlc-receive"),
		}
	}
}

impl FromStr for VtxoPolicyKind {
	type Err = String;
	fn from_str(s: &str) -> Result<Self, Self::Err> {
		Ok(match s {
			"pubkey" => Self::Pubkey,
			"checkpoint" => Self::Checkpoint,
			"server-htlc-send" => Self::ServerHtlcSend,
			"server-htlc-receive" => Self::ServerHtlcRecv,
			_ => return Err(format!("unknown VtxoPolicyKind: {}", s)),
		})
	}
}

impl serde::Serialize for VtxoPolicyKind {
	fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
		s.collect_str(self)
	}
}

impl<'de> serde::Deserialize<'de> for VtxoPolicyKind {
	fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
		struct Visitor;
		impl<'de> serde::de::Visitor<'de> for Visitor {
			type Value = VtxoPolicyKind;
			fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
				write!(f, "a VtxoPolicyKind")
			}
			fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
				VtxoPolicyKind::from_str(v).map_err(serde::de::Error::custom)
			}
		}
		d.deserialize_str(Visitor)
	}
}

/// Policy enabling VTXO protected with a public key.
///
/// This will build a taproot with 2 spending paths:
/// 1. The keyspend path allows Alice and Server to collaborate to spend
/// the VTXO.
///
/// 2. The script-spend path allows Alice to unilaterally spend the VTXO
/// after a delay.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PubkeyVtxoPolicy {
	pub user_pubkey: PublicKey,
}

impl From<PubkeyVtxoPolicy> for VtxoPolicy {
	fn from(policy: PubkeyVtxoPolicy) -> Self {
		Self::Pubkey(policy)
	}
}

impl PubkeyVtxoPolicy {
	/// Allows Alice to spend the VTXO after a delay.
	pub fn user_pubkey_claim_clause(&self, exit_delta: BlockDelta) -> DelayedSignClause {
		DelayedSignClause { pubkey: self.user_pubkey, block_delta: exit_delta }
	}

	pub fn clauses(&self, exit_delta: BlockDelta) -> Vec<VtxoClause> {
		vec![self.user_pubkey_claim_clause(exit_delta).into()]
	}

	pub fn taproot(
		&self,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
	) -> taproot::TaprootSpendInfo {
		let combined_pk = musig::combine_keys([self.user_pubkey, server_pubkey]);

		let user_pubkey_claim_clause = self.user_pubkey_claim_clause(exit_delta);
		taproot::TaprootBuilder::new()
			.add_leaf(0, user_pubkey_claim_clause.tapscript()).unwrap()
			.finalize(&SECP, combined_pk).unwrap()
	}
}

/// Policy enabling server checkpoints
///
/// This will build a taproot with 2 clauses:
/// 1. The keyspend path allows Alice and Server to collaborate to spend
/// the checkpoint.
///
/// 2. The script-spend path allows Server to spend the checkpoint after
/// the expiry height.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CheckpointVtxoPolicy {
	pub user_pubkey: PublicKey,
}

impl From<CheckpointVtxoPolicy> for VtxoPolicy {
	fn from(policy: CheckpointVtxoPolicy) -> Self {
		Self::Checkpoint(policy)
	}
}

impl CheckpointVtxoPolicy {
	/// Allows Server to spend the checkpoint after expiry height.
	pub fn server_sweeping_clause(
		&self,
		expiry_height: BlockHeight,
		server_pubkey: PublicKey,
	) -> TimelockSignClause {
		TimelockSignClause { pubkey: server_pubkey, timelock_height: expiry_height }
	}

	pub fn clauses(
		&self,
		expiry_height: BlockHeight,
		server_pubkey: PublicKey,
	) -> Vec<VtxoClause> {
		vec![self.server_sweeping_clause(expiry_height, server_pubkey).into()]
	}

	pub fn taproot(
		&self,
		server_pubkey: PublicKey,
		expiry_height: BlockHeight,
	) -> taproot::TaprootSpendInfo {
		let combined_pk = musig::combine_keys([self.user_pubkey, server_pubkey]);
		let server_sweeping_clause = self.server_sweeping_clause(expiry_height, server_pubkey);

		taproot::TaprootBuilder::new()
			.add_leaf(0, server_sweeping_clause.tapscript()).unwrap()
			.finalize(&SECP, combined_pk).unwrap()
	}
}

/// Policy enabling outgoing Lightning payments.
///
/// This will build a taproot with 3 clauses:
/// 1. The keyspend path allows Alice and Server to collaborate to spend
/// the HTLC. The Server can use this path to revoke the HTLC if payment
/// failed
///
/// 2. The script-spend path contains one leaf that allows Server to spend
/// the HTLC after the expiry, if it knows the preimage. Server can use
/// this path if Alice tries to spend using her clause.
///
/// 3. The second leaf allows Alice to spend the HTLC after its expiry
/// and with a delay. Alice must use this path if the server fails to
/// provide the preimage and refuse to revoke the HTLC. It will either
/// force the Server to reveal the preimage (by spending using her clause)
/// or give Alice her money back.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ServerHtlcSendVtxoPolicy {
	pub user_pubkey: PublicKey,
	pub payment_hash: PaymentHash,
	pub htlc_expiry: BlockHeight,
}

impl From<ServerHtlcSendVtxoPolicy> for VtxoPolicy {
	fn from(policy: ServerHtlcSendVtxoPolicy) -> Self {
		Self::ServerHtlcSend(policy)
	}
}

impl ServerHtlcSendVtxoPolicy {
	/// Allows Server to spend the HTLC after the delta, if it knows the
	/// preimage. Server can use this path if Alice tries to spend using her
	/// clause.
	pub fn server_reveals_preimage_clause(
		&self,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
	) -> HashDelaySignClause {
		HashDelaySignClause {
			pubkey: server_pubkey,
			payment_hash: self.payment_hash,
			block_delta: exit_delta
		}
	}

	/// Allows Alice to spend the HTLC after its expiry and with a delay.
	/// Alice must use this path if the server fails to provide the preimage
	/// and refuse to revoke the HTLC. It will either force the server to
	/// reveal the preimage (by spending using its clause) or give Alice her
	/// money back.
	pub fn user_claim_after_expiry_clause(
		&self,
		exit_delta: BlockDelta,
	) -> DelayedTimelockSignClause {
		DelayedTimelockSignClause {
			pubkey: self.user_pubkey,
			timelock_height: self.htlc_expiry,
			block_delta: 2 * exit_delta
		}
	}


	pub fn clauses(&self, exit_delta: BlockDelta, server_pubkey: PublicKey) -> Vec<VtxoClause> {
		vec![
			self.server_reveals_preimage_clause(server_pubkey, exit_delta).into(),
			self.user_claim_after_expiry_clause(exit_delta).into(),
		]
	}

	pub fn taproot(&self, server_pubkey: PublicKey, exit_delta: BlockDelta) -> taproot::TaprootSpendInfo {
		let server_reveals_preimage_clause = self.server_reveals_preimage_clause(server_pubkey, exit_delta);
		let user_claim_after_expiry_clause = self.user_claim_after_expiry_clause(exit_delta);

		let combined_pk = musig::combine_keys([self.user_pubkey, server_pubkey]);
		bitcoin::taproot::TaprootBuilder::new()
			.add_leaf(1, server_reveals_preimage_clause.tapscript()).unwrap()
			.add_leaf(1, user_claim_after_expiry_clause.tapscript()).unwrap()
			.finalize(&SECP, combined_pk).unwrap()
	}
}


/// Policy enabling incoming Lightning payments.
///
/// This will build a taproot with 3 clauses:
/// 1. The keyspend path allows Alice and Server to collaborate to spend
/// the HTLC. This is the expected path to be used. Server should only
/// accept to collaborate if Alice reveals the preimage.
///
/// 2. The script-spend path contains one leaf that allows Server to spend
/// the HTLC after the expiry, with an exit delta delay. Server can use
/// this path if Alice tries to spend the HTLC using the 3rd path after
/// the HTLC expiry
///
/// 3. The second leaf allows Alice to spend the HTLC if she knows the
/// preimage, but with a greater exit delta delay than server's clause.
/// Alice must use this path if she revealed the preimage but Server
/// refused to collaborate.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ServerHtlcRecvVtxoPolicy {
	pub user_pubkey: PublicKey,
	pub payment_hash: PaymentHash,
	pub htlc_expiry_delta: BlockDelta,
	pub htlc_expiry: BlockHeight,
}

impl ServerHtlcRecvVtxoPolicy {
	/// Allows Alice to spend the HTLC if she knows the preimage, but with a
	/// greater exit delta delay than server's clause. Alice must use this
	/// path if she revealed the preimage but server refused to cosign
	/// claim VTXO.
	pub fn user_reveals_preimage_clause(&self, exit_delta: BlockDelta) -> HashDelaySignClause {
		HashDelaySignClause {
			pubkey: self.user_pubkey,
			payment_hash: self.payment_hash,
			block_delta: self.htlc_expiry_delta + exit_delta
		}
	}

	/// Allows Server to spend the HTLC after the HTLC expiry, with an exit
	/// delta delay. Server can use this path if Alice tries to spend the
	/// HTLC using her clause after the HTLC expiry.
	pub fn server_claim_after_expiry_clause(
		&self,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
	) -> DelayedTimelockSignClause {
		DelayedTimelockSignClause {
			pubkey: server_pubkey,
			timelock_height: self.htlc_expiry,
			block_delta: exit_delta
		}
	}

	pub fn clauses(&self, exit_delta: BlockDelta, server_pubkey: PublicKey) -> Vec<VtxoClause> {
		vec![
			self.user_reveals_preimage_clause(exit_delta).into(),
			self.server_claim_after_expiry_clause(server_pubkey, exit_delta).into(),
		]
	}

	pub fn taproot(&self, server_pubkey: PublicKey, exit_delta: BlockDelta) -> taproot::TaprootSpendInfo {
		let server_claim_after_expiry_clause = self.server_claim_after_expiry_clause(server_pubkey, exit_delta);
		let user_reveals_preimage_clause = self.user_reveals_preimage_clause(exit_delta);

		let combined_pk = musig::combine_keys([self.user_pubkey, server_pubkey]);
		bitcoin::taproot::TaprootBuilder::new()
			.add_leaf(1, server_claim_after_expiry_clause.tapscript()).unwrap()
			.add_leaf(1, user_reveals_preimage_clause.tapscript()).unwrap()
			.finalize(&SECP, combined_pk).unwrap()
	}
}

impl From<ServerHtlcRecvVtxoPolicy> for VtxoPolicy {
	fn from(policy: ServerHtlcRecvVtxoPolicy) -> Self {
		Self::ServerHtlcRecv(policy)
	}
}

/// The output policy of the VTXO.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum VtxoPolicy {
	/// Standard VTXO output protected with a public key.
	///
	/// This can be the result of either:
	/// - a board
	/// - a round
	/// - an arkoor tx
	/// - change from a LN payment
	Pubkey(PubkeyVtxoPolicy),
	/// A policy which returns all funds to the server after expiry
	Checkpoint(CheckpointVtxoPolicy),
	/// A VTXO that represents an HTLC with the Ark server to send money.
	ServerHtlcSend(ServerHtlcSendVtxoPolicy),
	/// A VTXO that represents an HTLC with the Ark server to receive money.
	ServerHtlcRecv(ServerHtlcRecvVtxoPolicy),
}

impl VtxoPolicy {
	pub fn new_pubkey(user_pubkey: PublicKey) -> Self {
		Self::Pubkey(PubkeyVtxoPolicy { user_pubkey })
	}

	pub fn new_checkpoint(user_pubkey: PublicKey) -> Self {
		Self::Checkpoint(CheckpointVtxoPolicy { user_pubkey })
	}

	pub fn new_server_htlc_send(
		user_pubkey: PublicKey,
		payment_hash: PaymentHash,
		htlc_expiry: BlockHeight,
	) -> Self {
		Self::ServerHtlcSend(ServerHtlcSendVtxoPolicy { user_pubkey, payment_hash, htlc_expiry })
	}

	/// Creates a new htlc from server to client
	/// - user_pubkey: A public key owned by the client
	/// - payment_hash: The payment hash, the client can claim the HTLC
	/// by revealing the corresponding pre-image
	/// - htlc_expiry: An absolute blockheight at which the HTLC expires
	/// - htlc_expiry_delta: A safety margin for the server. If the user
	/// tries to exit after time-out the server will have at-least
	/// `htlc_expiry_delta` blocks to claim the payment
	pub fn new_server_htlc_recv(
		user_pubkey: PublicKey,
		payment_hash: PaymentHash,
		htlc_expiry: BlockHeight,
		htlc_expiry_delta: BlockDelta,
	) -> Self {
		Self::ServerHtlcRecv(ServerHtlcRecvVtxoPolicy {
			user_pubkey, payment_hash, htlc_expiry, htlc_expiry_delta,
		})
	}

	pub fn as_pubkey(&self) -> Option<&PubkeyVtxoPolicy> {
		match self {
			Self::Pubkey(v) => Some(v),
			_ => None,
		}
	}

	pub fn as_server_htlc_send(&self) -> Option<&ServerHtlcSendVtxoPolicy> {
		match self {
			Self::ServerHtlcSend(v) => Some(v),
			_ => None,
		}
	}

	pub fn as_server_htlc_recv(&self) -> Option<&ServerHtlcRecvVtxoPolicy> {
		match self {
			Self::ServerHtlcRecv(v) => Some(v),
			_ => None,
		}
	}

	/// The policy type id.
	pub fn policy_type(&self) -> VtxoPolicyKind {
		match self {
			Self::Pubkey { .. } => VtxoPolicyKind::Pubkey,
			Self::Checkpoint { .. } => VtxoPolicyKind::Checkpoint,
			Self::ServerHtlcSend { .. } => VtxoPolicyKind::ServerHtlcSend,
			Self::ServerHtlcRecv { .. } => VtxoPolicyKind::ServerHtlcRecv,
		}
	}

	/// Whether a [Vtxo](crate::Vtxo) with this output can be spend in an arkoor tx.
	pub fn is_arkoor_compatible(&self) -> bool {
		match self {
			Self::Pubkey { .. } => true,
			Self::Checkpoint { .. } => true,
			Self::ServerHtlcSend { .. } => false,
			Self::ServerHtlcRecv { .. } => false,
		}
	}

	/// The public key used to cosign arkoor txs spending a [Vtxo](crate::Vtxo)
	/// with this output.
	/// This will return [None] if [VtxoPolicy::is_arkoor_compatible] returns false.
	pub fn arkoor_pubkey(&self) -> Option<PublicKey> {
		match self {
			Self::Pubkey(PubkeyVtxoPolicy { user_pubkey }) => Some(*user_pubkey),
			Self::Checkpoint(CheckpointVtxoPolicy { user_pubkey }) => Some(*user_pubkey),
			Self::ServerHtlcSend(ServerHtlcSendVtxoPolicy { user_pubkey, .. }) => Some(*user_pubkey),
			Self::ServerHtlcRecv(ServerHtlcRecvVtxoPolicy { user_pubkey, .. }) => Some(*user_pubkey),
		}
	}

	/// Returns the user pubkey associated with a [Vtxo](crate::Vtxo) with this output.
	pub fn user_pubkey(&self) -> PublicKey {
		match self {
			Self::Pubkey(PubkeyVtxoPolicy { user_pubkey }) => *user_pubkey,
			Self::Checkpoint(CheckpointVtxoPolicy { user_pubkey }) => *user_pubkey,
			Self::ServerHtlcSend(ServerHtlcSendVtxoPolicy { user_pubkey, .. }) => *user_pubkey,
			Self::ServerHtlcRecv(ServerHtlcRecvVtxoPolicy { user_pubkey, .. }) => *user_pubkey,
		}
	}

	pub fn taproot(
		&self,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
		expiry_height: BlockHeight,
	) -> taproot::TaprootSpendInfo {
		match self {
			Self::Pubkey(policy) => policy.taproot(server_pubkey, exit_delta),
			Self::Checkpoint(policy) => policy.taproot(server_pubkey, expiry_height),
			Self::ServerHtlcSend(policy) => policy.taproot(server_pubkey, exit_delta),
			Self::ServerHtlcRecv(policy) => policy.taproot(server_pubkey, exit_delta),
		}
	}

	pub(crate) fn script_pubkey(
		&self,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
		expiry_height: BlockHeight,
	) -> ScriptBuf {
		self.taproot(server_pubkey, exit_delta, expiry_height).script_pubkey()
	}

	pub(crate) fn txout(
		&self,
		amount: Amount,
		server_pubkey: PublicKey,
		exit_delta: BlockDelta,
		expiry_height: BlockHeight,
	) -> TxOut {
		TxOut {
			value: amount,
			script_pubkey: self.script_pubkey(server_pubkey, exit_delta, expiry_height),
		}
	}

	pub fn clauses(
		&self,
		exit_delta: u16,
		expiry_height: BlockHeight,
		server_pubkey: PublicKey,
	) -> Vec<VtxoClause> {
		match self {
			Self::Pubkey(policy) => policy.clauses(exit_delta),
			Self::Checkpoint(policy) => policy.clauses(expiry_height, server_pubkey),
			Self::ServerHtlcSend(policy) => policy.clauses(exit_delta, server_pubkey),
			Self::ServerHtlcRecv(policy) => policy.clauses(exit_delta, server_pubkey),
		}
	}
}