diff --git a/crates/aldabra-dao/src/builder/escrow_refund_timeout.rs b/crates/aldabra-dao/src/builder/escrow_refund_timeout.rs new file mode 100644 index 0000000..8e8a055 --- /dev/null +++ b/crates/aldabra-dao/src/builder/escrow_refund_timeout.rs @@ -0,0 +1,470 @@ +//! Build an unsigned `escrow_refund_timeout_unsigned` transaction. +//! +//! ⚠️ WIP / UNAUDITED. Feature-gated behind `escrow_wip`. +//! +//! ## What this tx does +//! +//! Plutus V3 spend that consumes an `Open` escrow whose `open_deadline` +//! has elapsed and refunds every contributor to their enterprise +//! (null-stake) address. No signer required — the time gate is +//! sufficient. This is the "no agreement reached → bail out" path. +//! +//! Structurally identical to `escrow_veto` (multi-output refund per +//! deposit) but with different validator gates: +//! +//! | Branch | State req. | Time gate | Signer req. | +//! |------------|------------|---------------------------------|-------------------| +//! | Veto | Agreed | none | party_a OR party_b| +//! | Refund | Open | `lower > open_deadline_ms` | none | +//! +//! - **Inputs**: +//! - The escrow UTxO (Plutus V3 spend, redeemer = `Refund`). +//! - One funding wallet UTxO from the driver. +//! - **Collateral**: 1 ADA-only ≥5 ADA wallet UTxO from the driver. +//! - **Outputs**: One per deposit entry → contributor enterprise address. +//! + wallet change. +//! - **Disclosed signer**: driver pkh — needed to unlock funding + +//! collateral. Validator does NOT require a party signer. +//! +//! ## What the validator enforces (must match) +//! +//! From `aiken-escrow/validators/escrow.ak` Refund branch: +//! +//! 1. `d.state == Open`. +//! 2. Tx validity range lower bound `Some(lower)` (Finite). +//! 3. `lower > d.open_deadline_ms` — strict greater-than. +//! 4. `refund_outputs_satisfy(self.outputs, d.deposits)`. +//! +//! All four preflighted client-side. + +use pallas_addresses::Address; +use pallas_codec::minicbor; +use pallas_crypto::hash::Hash; +use pallas_txbuilder::{BuildConway, ExUnits, Input, Output, ScriptKind, StagingTransaction}; + +use crate::agora::escrow::{EscrowRedeemer, EscrowState, PKH_LEN}; +use crate::config::{DaoConfig, DaoNetwork}; +use crate::error::{DaoError, DaoResult}; + +use super::escrow_deposit::{EscrowUtxoIn, ESCROW_SPEND_EX_UNITS}; +use super::escrow_veto::enterprise_address_for; +use super::proposal_create::{ + parse_address, parse_script_hash, parse_tx_hash, WalletUtxo, MIN_COLLATERAL_LOVELACE, +}; + +const WALLET_CHANGE_MIN_LOVELACE: u64 = 1_000_000; + +/// Same below-floor topup floor as escrow_veto. Validator's +/// value_geq_flat permits paying more than the deposit's value, so +/// topping up keeps below-min-utxo deposits submittable. +const REFUND_OUTPUT_MIN_LOVELACE: u64 = 1_000_000; + +/// Args bundle for [`build_unsigned_escrow_refund_timeout`]. +#[derive(Debug, Clone)] +pub struct EscrowRefundTimeoutArgs { + pub cfg: DaoConfig, + pub escrow_script_address: String, + pub validator_script_cbor: Vec, + pub escrow_in: EscrowUtxoIn, + /// Whoever's driving — pays fee, holds collateral, gets change. + /// Doesn't need to be a party. Validator doesn't enforce a signer + /// for Refund — the time gate is the gate. + pub driver_pkh: [u8; PKH_LEN], + pub change_address: String, + pub wallet_utxos: Vec, + /// Slot to set `valid_from_slot(...)`. Must encode a posix-ms + /// `> open_deadline_ms`. + pub validity_lower_slot: u64, + /// POSIX-ms equivalent of `validity_lower_slot`. Used for the + /// preflight `lower > open_deadline_ms` check. + pub validity_lower_ms: i64, + pub validity_upper_slot: u64, + pub fee_lovelace: u64, + pub ex_units: ExUnits, +} + +/// What [`build_unsigned_escrow_refund_timeout`] returns. +#[derive(Debug, Clone)] +pub struct UnsignedEscrowRefundTimeout { + pub tx_cbor_hex: String, + pub tx_hash_hex: String, + pub refunds: Vec<(String, u64)>, + pub summary: String, +} + +/// Build the unsigned escrow_refund_timeout tx. +pub fn build_unsigned_escrow_refund_timeout( + args: EscrowRefundTimeoutArgs, +) -> DaoResult { + let datum_in = &args.escrow_in.datum; + + // ---- preflight ---------------------------------------------------------- + + // (1) state must be Open. + if datum_in.state != EscrowState::Open { + return Err(DaoError::State(format!( + "escrow state is {:?}, must be Open to Refund-timeout", + datum_in.state + ))); + } + + // (3) validity_lower_ms > open_deadline_ms (strict gt). + if args.validity_lower_ms <= datum_in.open_deadline_ms { + return Err(DaoError::State(format!( + "validity_lower_ms {} must be strictly > open_deadline_ms ({}); \ + open window has not elapsed", + args.validity_lower_ms, datum_in.open_deadline_ms + ))); + } + + if datum_in.deposits.is_empty() { + return Err(DaoError::State( + "escrow has no deposits — Refund-timeout of an empty escrow is a no-op".into(), + )); + } + + // ---- compute refund outputs (mirrors escrow_veto) ---------------------- + + let mut refund_lovelace_total: u64 = 0; + let mut topup_total: u64 = 0; + let mut refund_summaries: Vec<(String, u64)> = Vec::with_capacity(datum_in.deposits.len()); + let mut refund_outputs: Vec<(Address, u64, Vec<(Vec, Vec, i128)>)> = + Vec::with_capacity(datum_in.deposits.len()); + + for deposit in &datum_in.deposits { + let deposit_lovelace = deposit.value.lovelace(); + let pay_lovelace = deposit_lovelace.max(REFUND_OUTPUT_MIN_LOVELACE); + if pay_lovelace > deposit_lovelace { + topup_total = topup_total + .checked_add(pay_lovelace - deposit_lovelace) + .ok_or_else(|| DaoError::State("refund topup overflow".into()))?; + } + refund_lovelace_total = refund_lovelace_total + .checked_add(pay_lovelace) + .ok_or_else(|| DaoError::State("refund lovelace total overflow".into()))?; + + let mut assets: Vec<(Vec, Vec, i128)> = Vec::new(); + for (policy, entries) in &deposit.value.policies { + if policy.is_empty() { + continue; + } + for (name, qty) in entries { + assets.push((policy.clone(), name.clone(), *qty)); + } + } + + let addr = enterprise_address_for(deposit.contributor, args.cfg.network)?; + refund_outputs.push((addr, pay_lovelace, assets)); + refund_summaries.push((hex::encode(deposit.contributor), pay_lovelace)); + } + + // ---- redeemer + collateral + funding ----------------------------------- + + let redeemer_pd = EscrowRedeemer::Refund.to_plutus_data()?; + let redeemer_cbor = minicbor::to_vec(&redeemer_pd) + .map_err(|e| DaoError::Cbor(format!("refund redeemer encode: {e}")))?; + + let mut ada_only: Vec = args + .wallet_utxos + .iter() + .filter(|u| u.is_ada_only()) + .cloned() + .collect(); + ada_only.sort_by_key(|u| std::cmp::Reverse(u.lovelace)); + + let collateral = ada_only + .iter() + .rev() + .find(|u| u.lovelace >= MIN_COLLATERAL_LOVELACE) + .ok_or_else(|| { + DaoError::State(format!( + "no ada-only wallet UTxO ≥ {MIN_COLLATERAL_LOVELACE} lovelace for collateral" + )) + })? + .clone(); + + let funding = ada_only + .iter() + .find(|u| { + !(u.tx_hash_hex == collateral.tx_hash_hex && u.output_index == collateral.output_index) + }) + .cloned() + .ok_or_else(|| { + DaoError::State( + "need a SECOND ada-only wallet UTxO to fund the Refund (separate from collateral)" + .into(), + ) + })?; + + // ---- balance + change --------------------------------------------------- + + let total_in = args + .escrow_in + .lovelace + .checked_add(funding.lovelace) + .ok_or_else(|| DaoError::State("input lovelace overflow".into()))?; + let total_out = refund_lovelace_total + .checked_add(args.fee_lovelace) + .ok_or_else(|| DaoError::State("output lovelace overflow".into()))?; + let change_lovelace = total_in.checked_sub(total_out).ok_or_else(|| { + DaoError::State(format!( + "insufficient input: total_in={total_in} need={total_out} \ + (refunds={refund_lovelace_total} + fee={}; topup={topup_total})", + args.fee_lovelace + )) + })?; + if change_lovelace > 0 && change_lovelace < WALLET_CHANGE_MIN_LOVELACE { + return Err(DaoError::State(format!( + "change lovelace {change_lovelace} below min UTxO ({WALLET_CHANGE_MIN_LOVELACE}); top up wallet" + ))); + } + + // ---- assemble pallas StagingTransaction -------------------------------- + + let change_addr = parse_address(&args.change_address)?; + let escrow_input = Input::new( + parse_tx_hash(&args.escrow_in.tx_hash_hex)?, + args.escrow_in.output_index as u64, + ); + let funding_input = Input::new( + parse_tx_hash(&funding.tx_hash_hex)?, + funding.output_index as u64, + ); + let collateral_input = Input::new( + parse_tx_hash(&collateral.tx_hash_hex)?, + collateral.output_index as u64, + ); + + let network_id = match args.cfg.network { + DaoNetwork::Mainnet => 1u8, + DaoNetwork::Preprod | DaoNetwork::Preview => 0u8, + }; + + let mut staging = StagingTransaction::new(); + staging = staging.input(escrow_input.clone()); + staging = staging.input(funding_input); + staging = staging.collateral_input(collateral_input); + + for (addr, lovelace, assets) in refund_outputs { + let mut out = Output::new(addr, lovelace); + for (policy, name, qty) in assets { + let policy_hash = if policy.len() == 28 { + let mut a = [0u8; 28]; + a.copy_from_slice(&policy); + Hash::<28>::from(a) + } else { + return Err(DaoError::State(format!( + "deposit policy id has wrong length {} (expected 28)", + policy.len() + ))); + }; + out = out + .add_asset(policy_hash, name, qty as u64) + .map_err(|e| DaoError::Backend(format!("refund add_asset: {e}")))?; + } + staging = staging.output(out); + } + + if change_lovelace > 0 { + let mut change_output = Output::new(change_addr, change_lovelace); + for (policy_hex, name_hex, qty) in &funding.assets { + let policy = parse_script_hash(policy_hex)?; + let name = hex::decode(name_hex) + .map_err(|e| DaoError::Config(format!("funding asset name hex: {e}")))?; + change_output = change_output + .add_asset(policy, name, *qty) + .map_err(|e| DaoError::Backend(format!("add asset to change: {e}")))?; + } + staging = staging.output(change_output); + } + + staging = staging.script(ScriptKind::PlutusV3, args.validator_script_cbor); + staging = staging.add_spend_redeemer(escrow_input, redeemer_cbor, Some(args.ex_units)); + + staging = staging.fee(args.fee_lovelace).network_id(network_id); + + staging = staging.valid_from_slot(args.validity_lower_slot); + staging = staging.invalid_from_slot(args.validity_upper_slot); + + staging = staging.disclosed_signer(Hash::<28>::from(args.driver_pkh)); + + staging = staging.language_view( + ScriptKind::PlutusV3, + aldabra_core::plutus_cost_models::PLUTUS_V3_COST_MODEL_PREPROD.to_vec(), + ); + + let built = staging + .build_conway_raw() + .map_err(|e| DaoError::Backend(format!("build_conway_raw: {e}")))?; + + let tx_cbor_hex = hex::encode(&built.tx_bytes.0); + let tx_hash_hex = hex::encode(built.tx_hash.0); + + let summary = format!( + "escrow_refund_timeout_unsigned: driver={} refunds={} ({} lovelace total, topup={}, fee={})", + hex::encode(args.driver_pkh), + refund_summaries.len(), + refund_lovelace_total, + topup_total, + args.fee_lovelace, + ); + + Ok(UnsignedEscrowRefundTimeout { + tx_cbor_hex, + tx_hash_hex, + refunds: refund_summaries, + summary, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agora::escrow::{EscrowDatum, EscrowDeposit, EscrowValue}; + use crate::config::ScriptRefs; + + fn pkh(seed: u8) -> [u8; PKH_LEN] { + [seed; PKH_LEN] + } + + fn sample_cfg() -> DaoConfig { + DaoConfig { + name: "sulkta-escrow".into(), + description: None, + governor_addr: "addr_test1wqlzsnytzs4qv0trmhvw5cuyxnxk0qjq68crn85jj4lhv7qn4wym4".into(), + stakes_addr: "addr_test1wqlzsnytzs4qv0trmhvw5cuyxnxk0qjq68crn85jj4lhv7qn4wym4".into(), + treasury_addr: "addr_test1wqlzsnytzs4qv0trmhvw5cuyxnxk0qjq68crn85jj4lhv7qn4wym4".into(), + gov_token_policy: "00".repeat(28), + gov_token_name_hex: "".into(), + initial_spend: format!("{}#0", "00".repeat(32)), + max_cosigners: 5, + treasury_ref_config: "00".repeat(28), + network: DaoNetwork::Preprod, + proposal_addr: None, + stake_st_policy: None, + proposal_st_policy: None, + script_refs: ScriptRefs::default(), + } + } + + fn stub_v3_script() -> Vec { + vec![0x46, 0x01, 0x00, 0x00, 0x32, 0x22] + } + + fn sample_args( + state: EscrowState, + validity_lower_ms: i64, + deposits: Vec, + ) -> EscrowRefundTimeoutArgs { + let escrow_in = EscrowUtxoIn { + tx_hash_hex: "11".repeat(32), + output_index: 0, + lovelace: 12_000_000, + assets: vec![], + datum: EscrowDatum { + party_a: pkh(0xa1), + party_b: pkh(0xb2), + recipient: pkh(0xb2), + open_deadline_ms: 1_700_000_000_000, + lock_period_ms: 30 * 60 * 1000, + state, + deposits, + }, + }; + EscrowRefundTimeoutArgs { + cfg: sample_cfg(), + escrow_script_address: + "addr_test1wqlzsnytzs4qv0trmhvw5cuyxnxk0qjq68crn85jj4lhv7qn4wym4".into(), + validator_script_cbor: stub_v3_script(), + escrow_in, + driver_pkh: pkh(0xa1), + change_address: + "addr_test1qqqt0pru382hy9vjlsxv3ye02z50sfvt8xunscg5pgden77z73dpdfng2ctw2ekqplqgrljelz7h4dneac27nn3qx3rqqpavzj" + .into(), + wallet_utxos: vec![ + WalletUtxo { + tx_hash_hex: "22".repeat(32), + output_index: 0, + lovelace: 30_000_000, + assets: vec![], + }, + WalletUtxo { + tx_hash_hex: "33".repeat(32), + output_index: 0, + lovelace: 8_000_000, + assets: vec![], + }, + ], + validity_lower_slot: 50_001_000, + validity_lower_ms, + validity_upper_slot: 50_002_800, + fee_lovelace: 2_500_000, + ex_units: ESCROW_SPEND_EX_UNITS, + } + } + + #[test] + fn rejects_when_not_open() { + let agreed = EscrowState::Agreed { + agreed_at_ms: 1_699_999_900_000, + }; + let args = sample_args(agreed, 1_700_000_000_001, vec![]); + let err = build_unsigned_escrow_refund_timeout(args).unwrap_err(); + assert!(err.to_string().contains("must be Open")); + } + + #[test] + fn rejects_when_open_window_not_elapsed() { + // open_deadline_ms = 1_700_000_000_000; equal-to is NOT past. + let deposits = vec![EscrowDeposit { + contributor: pkh(0xa1), + value: EscrowValue::ada(5_000_000), + }]; + let args = sample_args(EscrowState::Open, 1_700_000_000_000, deposits); + let err = build_unsigned_escrow_refund_timeout(args).unwrap_err(); + assert!(err.to_string().contains("strictly >")); + } + + #[test] + fn rejects_empty_escrow() { + let args = sample_args(EscrowState::Open, 1_700_000_000_001, vec![]); + let err = build_unsigned_escrow_refund_timeout(args).unwrap_err(); + assert!(err.to_string().contains("no deposits")); + } + + #[test] + fn happy_path_two_contributors_full_refund() { + let deposits = vec![ + EscrowDeposit { + contributor: pkh(0xa1), + value: EscrowValue::ada(5_000_000), + }, + EscrowDeposit { + contributor: pkh(0xb2), + value: EscrowValue::ada(7_000_000), + }, + ]; + let unsigned = build_unsigned_escrow_refund_timeout(sample_args( + EscrowState::Open, + 1_700_000_000_001, + deposits, + )) + .unwrap(); + assert_eq!(unsigned.refunds.len(), 2); + assert_eq!(unsigned.refunds[0], (hex::encode(pkh(0xa1)), 5_000_000)); + assert_eq!(unsigned.refunds[1], (hex::encode(pkh(0xb2)), 7_000_000)); + } + + #[test] + fn anyone_can_drive_refund_validator_doesnt_enforce_signer() { + // Driver is a third party — that's allowed for Refund. + let deposits = vec![EscrowDeposit { + contributor: pkh(0xa1), + value: EscrowValue::ada(5_000_000), + }]; + let mut args = sample_args(EscrowState::Open, 1_700_000_000_001, deposits); + args.driver_pkh = pkh(0xff); + let unsigned = build_unsigned_escrow_refund_timeout(args).unwrap(); + assert!(unsigned.summary.contains(&hex::encode(pkh(0xff)))); + } +} diff --git a/crates/aldabra-dao/src/builder/mod.rs b/crates/aldabra-dao/src/builder/mod.rs index 379c3b7..202201c 100644 --- a/crates/aldabra-dao/src/builder/mod.rs +++ b/crates/aldabra-dao/src/builder/mod.rs @@ -31,6 +31,8 @@ pub mod escrow_deposit; #[cfg(feature = "escrow_wip")] pub mod escrow_open; #[cfg(feature = "escrow_wip")] +pub mod escrow_refund_timeout; +#[cfg(feature = "escrow_wip")] pub mod escrow_settle; #[cfg(feature = "escrow_wip")] pub mod escrow_veto;