//! The `budget_expr` module provides a domain-specific language for pa&yment plans. Users create BudgetExpr objects that //! are given to an interpreter. The interpreter listens for `Witness` transactions, //! which it uses to reduce the payment plan. When the budget is reduced to a //! `Payment`, the payment is executed. use chrono::prelude::*; use serde_derive::{Deserialize, Serialize}; use solana_sdk::hash::Hash; use solana_sdk::pubkey::Pubkey; use std::mem; /// The types of events a payment plan can process. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub enum Witness { /// The current time. Timestamp(DateTime), /// A signature from Pubkey. Signature, /// Account snapshot. AccountData(Hash, Pubkey), } /// Some amount of lamports that should be sent to the `to` `Pubkey`. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub struct Payment { /// Amount to be paid. pub lamports: u64, /// The `Pubkey` that `lamports` should be paid to. pub to: Pubkey, } /// The account constraints a Condition would wait on. /// Note: ideally this would be function that accepts an Account and returns /// a bool, but we don't have a way to pass functions over the wire. To simulate /// higher order programming, create your own program that includes an instruction /// that sets account data to a boolean. Pass that account key and program_id here. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub struct AccountConstraints { /// The account holder. pub key: Pubkey, /// The program id that must own the account at `key`. pub program_id: Pubkey, /// The hash of the data in the account at `key`. pub data_hash: Hash, } /// A data type representing a `Witness` that the payment plan is waiting on. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub enum Condition { /// Wait for a `Timestamp` `Witness` at or after the given `DateTime`. Timestamp(DateTime, Pubkey), /// Wait for a `Signature` `Witness` from `Pubkey`. Signature(Pubkey), /// Wait for the account with the given constraints. AccountData(AccountConstraints), } impl Condition { /// Return true if the given Witness satisfies this Condition. pub fn is_satisfied(&self, witness: &Witness, from: &Pubkey) -> bool { match (self, witness) { (Condition::Signature(pubkey), Witness::Signature) => pubkey == from, (Condition::Timestamp(dt, pubkey), Witness::Timestamp(last_time)) => { pubkey == from && dt <= last_time } ( Condition::AccountData(constraints), Witness::AccountData(actual_hash, program_id), ) => { constraints.program_id == *program_id && constraints.key == *from && constraints.data_hash == *actual_hash } _ => false, } } } /// A data type representing a payment plan. #[repr(C)] #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub enum BudgetExpr { /// Make a payment. Pay(Payment), /// Make a payment after some condition. After(Condition, Box), /// Either make a payment after one condition or a different payment after another /// condition, which ever condition is satisfied first. Or((Condition, Box), (Condition, Box)), /// Make a payment after both of two conditions are satisfied And(Condition, Condition, Box), } impl BudgetExpr { /// Create the simplest budget - one that pays `lamports` to Pubkey. pub fn new_payment(lamports: u64, to: &Pubkey) -> Self { BudgetExpr::Pay(Payment { lamports, to: *to }) } /// Create a budget that pays `lamports` to `to` after being witnessed by `from`. pub fn new_authorized_payment(from: &Pubkey, lamports: u64, to: &Pubkey) -> Self { BudgetExpr::After( Condition::Signature(*from), Box::new(Self::new_payment(lamports, to)), ) } /// Create a budget that pays `lamports` to `to` after witnessing account data in `account_pubkey` with the given hash. pub fn new_payment_when_account_data( account_pubkey: &Pubkey, account_program_id: &Pubkey, account_hash: Hash, lamports: u64, to: &Pubkey, ) -> Self { BudgetExpr::After( Condition::AccountData(AccountConstraints { key: *account_pubkey, program_id: *account_program_id, data_hash: account_hash, }), Box::new(Self::new_payment(lamports, to)), ) } /// Create a budget that pays `lamports` to `to` after being witnessed by `witness` unless /// canceled with a signature from `from`. pub fn new_cancelable_authorized_payment( witness: &Pubkey, lamports: u64, to: &Pubkey, from: Option, ) -> Self { if from.is_none() { return Self::new_authorized_payment(witness, lamports, to); } let from = from.unwrap(); BudgetExpr::Or( ( Condition::Signature(*witness), Box::new(BudgetExpr::new_payment(lamports, to)), ), ( Condition::Signature(from), Box::new(BudgetExpr::new_payment(lamports, &from)), ), ) } /// Create a budget that pays lamports` to `to` after being witnessed by 2x `from`s pub fn new_2_2_multisig_payment( from0: &Pubkey, from1: &Pubkey, lamports: u64, to: &Pubkey, ) -> Self { BudgetExpr::And( Condition::Signature(*from0), Condition::Signature(*from1), Box::new(Self::new_payment(lamports, to)), ) } /// Create a budget that pays `lamports` to `to` after the given DateTime signed /// by `dt_pubkey`. pub fn new_future_payment( dt: DateTime, dt_pubkey: &Pubkey, lamports: u64, to: &Pubkey, ) -> Self { BudgetExpr::After( Condition::Timestamp(dt, *dt_pubkey), Box::new(Self::new_payment(lamports, to)), ) } /// Create a budget that pays `lamports` to `to` after the given DateTime /// signed by `dt_pubkey` unless canceled by `from`. pub fn new_cancelable_future_payment( dt: DateTime, dt_pubkey: &Pubkey, lamports: u64, to: &Pubkey, from: Option, ) -> Self { if from.is_none() { return Self::new_future_payment(dt, dt_pubkey, lamports, to); } let from = from.unwrap(); BudgetExpr::Or( ( Condition::Timestamp(dt, *dt_pubkey), Box::new(Self::new_payment(lamports, to)), ), ( Condition::Signature(from), Box::new(Self::new_payment(lamports, &from)), ), ) } /// Return Payment if the budget requires no additional Witnesses. pub fn final_payment(&self) -> Option { match self { BudgetExpr::Pay(payment) => Some(payment.clone()), _ => None, } } /// Return true if the budget spends exactly `spendable_lamports`. pub fn verify(&self, spendable_lamports: u64) -> bool { match self { BudgetExpr::Pay(payment) => payment.lamports == spendable_lamports, BudgetExpr::After(_, sub_expr) | BudgetExpr::And(_, _, sub_expr) => { sub_expr.verify(spendable_lamports) } BudgetExpr::Or(a, b) => { a.1.verify(spendable_lamports) && b.1.verify(spendable_lamports) } } } /// Apply a witness to the budget to see if the budget can be reduced. /// If so, modify the budget in-place. pub fn apply_witness(&mut self, witness: &Witness, from: &Pubkey) { let new_expr = match self { BudgetExpr::After(cond, sub_expr) if cond.is_satisfied(witness, from) => { Some(sub_expr.clone()) } BudgetExpr::Or((cond, sub_expr), _) if cond.is_satisfied(witness, from) => { Some(sub_expr.clone()) } BudgetExpr::Or(_, (cond, sub_expr)) if cond.is_satisfied(witness, from) => { Some(sub_expr.clone()) } BudgetExpr::And(cond0, cond1, sub_expr) => { if cond0.is_satisfied(witness, from) { Some(Box::new(BudgetExpr::After(cond1.clone(), sub_expr.clone()))) } else if cond1.is_satisfied(witness, from) { Some(Box::new(BudgetExpr::After(cond0.clone(), sub_expr.clone()))) } else { None } } _ => None, }; if let Some(expr) = new_expr { mem::replace(self, *expr); } } } #[cfg(test)] mod tests { use super::*; #[test] fn test_signature_satisfied() { let from = Pubkey::default(); assert!(Condition::Signature(from).is_satisfied(&Witness::Signature, &from)); } #[test] fn test_timestamp_satisfied() { let dt1 = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10); let dt2 = Utc.ymd(2014, 11, 14).and_hms(10, 9, 8); let from = Pubkey::default(); assert!(Condition::Timestamp(dt1, from).is_satisfied(&Witness::Timestamp(dt1), &from)); assert!(Condition::Timestamp(dt1, from).is_satisfied(&Witness::Timestamp(dt2), &from)); assert!(!Condition::Timestamp(dt2, from).is_satisfied(&Witness::Timestamp(dt1), &from)); } #[test] fn test_verify() { let dt = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10); let from = Pubkey::default(); let to = Pubkey::default(); assert!(BudgetExpr::new_payment(42, &to).verify(42)); assert!(BudgetExpr::new_authorized_payment(&from, 42, &to).verify(42)); assert!(BudgetExpr::new_future_payment(dt, &from, 42, &to).verify(42)); assert!( BudgetExpr::new_cancelable_future_payment(dt, &from, 42, &to, Some(from)).verify(42) ); } #[test] fn test_authorized_payment() { let from = Pubkey::default(); let to = Pubkey::default(); let mut expr = BudgetExpr::new_authorized_payment(&from, 42, &to); expr.apply_witness(&Witness::Signature, &from); assert_eq!(expr, BudgetExpr::new_payment(42, &to)); } #[test] fn test_future_payment() { let dt = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10); let from = Pubkey::new_rand(); let to = Pubkey::new_rand(); let mut expr = BudgetExpr::new_future_payment(dt, &from, 42, &to); expr.apply_witness(&Witness::Timestamp(dt), &from); assert_eq!(expr, BudgetExpr::new_payment(42, &to)); } #[test] fn test_unauthorized_future_payment() { // Ensure timestamp will only be acknowledged if it came from the // whitelisted public key. let dt = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10); let from = Pubkey::new_rand(); let to = Pubkey::new_rand(); let mut expr = BudgetExpr::new_future_payment(dt, &from, 42, &to); let orig_expr = expr.clone(); expr.apply_witness(&Witness::Timestamp(dt), &to); // <-- Attack! assert_eq!(expr, orig_expr); } #[test] fn test_cancelable_future_payment() { let dt = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10); let from = Pubkey::default(); let to = Pubkey::default(); let mut expr = BudgetExpr::new_cancelable_future_payment(dt, &from, 42, &to, Some(from)); expr.apply_witness(&Witness::Timestamp(dt), &from); assert_eq!(expr, BudgetExpr::new_payment(42, &to)); let mut expr = BudgetExpr::new_cancelable_future_payment(dt, &from, 42, &to, Some(from)); expr.apply_witness(&Witness::Signature, &from); assert_eq!(expr, BudgetExpr::new_payment(42, &from)); } #[test] fn test_2_2_multisig_payment() { let from0 = Pubkey::new_rand(); let from1 = Pubkey::new_rand(); let to = Pubkey::default(); let mut expr = BudgetExpr::new_2_2_multisig_payment(&from0, &from1, 42, &to); expr.apply_witness(&Witness::Signature, &from0); assert_eq!(expr, BudgetExpr::new_authorized_payment(&from1, 42, &to)); } #[test] fn test_multisig_after_sig() { let from0 = Pubkey::new_rand(); let from1 = Pubkey::new_rand(); let from2 = Pubkey::new_rand(); let to = Pubkey::default(); let expr = BudgetExpr::new_2_2_multisig_payment(&from0, &from1, 42, &to); let mut expr = BudgetExpr::After(Condition::Signature(from2), Box::new(expr)); expr.apply_witness(&Witness::Signature, &from2); expr.apply_witness(&Witness::Signature, &from0); assert_eq!(expr, BudgetExpr::new_authorized_payment(&from1, 42, &to)); } #[test] fn test_multisig_after_ts() { let from0 = Pubkey::new_rand(); let from1 = Pubkey::new_rand(); let dt = Utc.ymd(2014, 11, 11).and_hms(7, 7, 7); let to = Pubkey::default(); let expr = BudgetExpr::new_2_2_multisig_payment(&from0, &from1, 42, &to); let mut expr = BudgetExpr::After(Condition::Timestamp(dt, from0), Box::new(expr)); expr.apply_witness(&Witness::Timestamp(dt), &from0); assert_eq!( expr, BudgetExpr::new_2_2_multisig_payment(&from0, &from1, 42, &to) ); expr.apply_witness(&Witness::Signature, &from0); assert_eq!(expr, BudgetExpr::new_authorized_payment(&from1, 42, &to)); } }