feat(escrow_wip): build_unsigned_escrow_refund_timeout builder

Plutus V3 spend that consumes an Open escrow whose open_deadline has
elapsed and refunds every contributor. Same multi-output refund shape
as Veto, different validator gates: state==Open AND lower >
open_deadline_ms (strict gt). No required signer — time gate is the
only gate.

Reuses enterprise_address_for from escrow_veto. 5 tests: not-Open
reject, open-window-not-elapsed reject (off-by-one strict gt),
empty-escrow reject, two-contributor full refund happy path,
outsider driver works.

Closes the 5-redeemer escrow surface: open + deposit + agree + veto +
settle + refund_timeout. 35/35 escrow builder tests pass.

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<u8>,
+    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<WalletUtxo>,
+    /// 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<UnsignedEscrowRefundTimeout> {
+    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<u8>, Vec<u8>, 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<u8>, Vec<u8>, 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<WalletUtxo> = 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<u8> {
+        vec![0x46, 0x01, 0x00, 0x00, 0x32, 0x22]
+    }
+
+    fn sample_args(
+        state: EscrowState,
+        validity_lower_ms: i64,
+        deposits: Vec<EscrowDeposit>,
+    ) -> 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))));
+    }
+}

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;