decdn_cli/commands/

bond.rs

//! `decdn node bond` — stake to a capacity tier (ADR 019 § Step 2.1–2.2).
//!
//! Idempotent "stake to capacity tier N". The operator passes only `--mbps`;
//! the TOKEN amount is read from the on-chain `bondRequired` curve. The
//! command tops the active bond up to `max(minBond, bondRequired(mbps))`,
//! approving and bonding only the shortfall, then `declareMbps(mbps)`. Bonding
//! the shortfall (rather than a flat amount) is what makes a re-run after a
//! partial failure converge instead of over-bonding. A precondition for
//! `decdn node register`.

use std::io;
use std::path::Path;

use alloy::primitives::{Address, B256, U256};
use alloy::providers::Provider;
use anyhow::Context;
use decdn_common::cli;
use decdn_incentive::Erc20;
use decdn_incentive::capacity_bond::CapacityBond;

use crate::commands::chain_ctx;

/// Entry point for `decdn node bond`.
pub async fn run(args: &cli::BondArgs, global_config: Option<&Path>) -> anyhow::Result<()> {
    let config_path = args.chain.common.config.as_deref().or(global_config);
    let file = chain_ctx::load_optional_config(config_path)?;
    let resolved = chain_ctx::resolve(&args.chain, &file)?;
    let cb_addr = resolved.capacity_bond_address;

    let signer = chain_ctx::load_operator_signer(&args.chain.common, &resolved.keystore).await?;
    let operator = signer.address();
    let provider = decdn_client::provider::build_provider(&resolved.rpc_url, &signer)?;
    let bond = CapacityBond::new(cb_addr, &provider);

    let mbps = U256::from(args.mbps);
    let plan = build_plan(&bond, operator, mbps, cb_addr).await?;

    if args.chain.common.dry_run {
        let mut out = io::stdout().lock();
        write_plan(
            &mut out,
            &plan,
            args.chain.common.json,
            &Outcome::default(),
            true,
        )
        .context("failed to write dry-run output")?;
        return Ok(());
    }

    // The outcome is owned HERE, not inside `execute`, so a partially-applied
    // sequence survives the error (#1355, mirroring what #1353 did for
    // `unbond`). `execute` sends up to three transactions; if `declareMbps`
    // fails after `bond` mined, those hashes are the operator's only record that
    // their TOKEN moved into `CapacityBond`. Returning `Err` with the outcome
    // still inside `execute` would drop it and print nothing at all.
    let mut outcome = Outcome::default();
    let result = execute(
        &bond,
        &provider,
        &plan,
        operator,
        cb_addr,
        mbps,
        &mut outcome,
    )
    .await;

    let mut out = io::stdout().lock();
    let write_result = write_plan(&mut out, &plan, args.chain.common.json, &outcome, false);
    drop(out);
    // A failed stdout write must never displace the chain error: under
    // `decdn node bond --json | head`, Rust ignores SIGPIPE and `writeln!`
    // returns EPIPE, so `?`-ing this first would swallow the very
    // "bond ALREADY LANDED" message #1355 exists to deliver. Echo it to stderr
    // (stdout is broken by hypothesis) and let the chain error win.
    if let Err(err) = &write_result {
        eprintln!("warning: failed to write bond result to stdout: {err}");
    }
    result.with_context(|| resume_hint(&outcome))?;
    write_result.context("failed to write result")?;
    Ok(())
}

/// Operator-facing guidance attached to a failed [`execute`], naming the latest
/// step that may have taken effect.
///
/// Reads [`Outcome`] as [`chain_ctx::send`] populates it: `Some` means "may have
/// taken effect" — confirmed success OR broadcast-with-an-unreadable-receipt —
/// and `None` means "definitively not applied" (never sent, or a confirmed
/// revert). That distinction is the whole point (#1355 review): the earlier
/// wording asserted strong negatives ("no TOKEN was transferred", "on-chain
/// state is unchanged") and told the operator to re-run immediately, which is
/// unsafe. alloy's nonce filler resolves against the *pending* block, so
/// re-running while a `bond` tx is still in the mempool takes the next nonce,
/// re-reads a stale `activeBond`, and submits a *second* top-up — doubling the
/// bond rather than converging.
///
/// Matched over all three steps rather than the two that can be outstanding
/// today. `declare` is currently unreachable in an `Err` (it is the last thing
/// `execute` does), but that is a control-flow fact this function cannot see; a
/// fourth step added later would otherwise silently make the guidance name the
/// wrong transaction.
pub(crate) fn resume_hint(outcome: &Outcome) -> String {
    let pending = |step: &str, tx: B256, rest: &str| {
        format!(
            "{step} tx {tx:#x} may have taken effect — it was submitted, and if the error \
             below is a receipt-fetch timeout rather than a revert its outcome is still \
             unknown. {rest} Do NOT re-run until {tx:#x} has settled: re-running while it \
             is pending takes the next nonce and submits a second transaction, which for a \
             bond doubles it."
        )
    };
    match (outcome.declare, outcome.bond, outcome.approve) {
        (Some(tx), ..) => pending(
            "declareMbps",
            tx,
            "The bond itself is in place; only a step after the tier declaration failed.",
        ),
        (_, Some(tx), _) => pending(
            "bond",
            tx,
            "If it mined, the TOKEN is held by CapacityBond (confirm with `activeBond`) and \
             only the capacity tier is missing; a re-run then tops up just the remaining \
             shortfall.",
        ),
        (_, _, Some(tx)) => pending(
            "approve",
            tx,
            "It only grants an allowance — no TOKEN moves until the bond transaction \
             itself lands, and none is recorded as having done so.",
        ),
        (None, None, None) => "no transaction is recorded as having taken effect: either \
             nothing was broadcast (a pre-flight gas estimate or a pre-flight balance check \
             rejecting the call), or one was broadcast and confirmed reverted. Check the \
             cause below for a tx hash, and the pending nonce, before re-running"
            .to_string(),
    }
}

/// What `bond` intends to do, computed from chain state. `pub(crate)` so
/// `decdn setup` can reuse the same top-up plan for its pre-flight checks and
/// confirmation prompt without re-deriving the curve math (#933).
pub(crate) struct Plan {
    pub(crate) mbps: u64,
    pub(crate) token: Address,
    pub(crate) capacity_bond: Address,
    /// `bondRequired(mbps)` under the current curve (base units).
    pub(crate) required: U256,
    /// `max(minBond, required)` — what `registerNode` needs in place.
    pub(crate) target: U256,
    /// Active bond before this command.
    pub(crate) prior: U256,
    /// `target − prior` (saturating) — what we approve + bond.
    pub(crate) shortfall: U256,
    /// Whether `declareMbps` is needed (the operator isn't already at `mbps`).
    pub(crate) needs_declare: bool,
}

/// Transaction hashes from a non-dry run; `None` for steps that were skipped
/// (no shortfall, allowance already sufficient, tier already declared).
#[derive(Default)]
pub(crate) struct Outcome {
    pub(crate) approve: Option<B256>,
    pub(crate) bond: Option<B256>,
    pub(crate) declare: Option<B256>,
}

/// Read chain state and compute the top-up plan. Validates the tier against
/// the on-chain capacity band up front, so an out-of-band `--mbps` is rejected
/// before any bond is posted rather than stranding one behind a `declareMbps`
/// revert.
pub(crate) async fn build_plan<P: Provider + Clone>(
    bond: &CapacityBond::CapacityBondInstance<P>,
    operator: Address,
    mbps: U256,
    cb_addr: Address,
) -> anyhow::Result<Plan> {
    let ctx = || format!("failed to read CapacityBond state at {cb_addr}");
    let min_cap = bond.minCapacityMbps().call().await.with_context(ctx)?;
    let max_cap = bond.maxCapacityMbps().call().await.with_context(ctx)?;
    anyhow::ensure!(
        mbps >= min_cap && mbps <= max_cap,
        "declared capacity {mbps} Mbps is outside the on-chain band [{min_cap}, {max_cap}]; \
         declareMbps would revert",
    );

    let required = bond.bondRequired(mbps).call().await.with_context(ctx)?;
    let min_bond = bond.minBond().call().await.with_context(ctx)?;
    let prior = bond.activeBond(operator).call().await.with_context(ctx)?;
    let declared = bond.declaredMbps(operator).call().await.with_context(ctx)?;
    let token = bond.token().call().await.with_context(ctx)?;

    let target = min_bond.max(required);
    Ok(Plan {
        mbps: u64::try_from(mbps).unwrap_or(u64::MAX),
        token,
        capacity_bond: cb_addr,
        required,
        target,
        prior,
        shortfall: target.saturating_sub(prior),
        needs_declare: declared != mbps,
    })
}

/// Submit the needed transactions in order: approve (if allowance short) →
/// bond (if shortfall) → declareMbps (if not already at the tier). Each step
/// is independently skippable, which is what makes the command idempotent.
///
/// `outcome` is a caller-owned accumulator rather than a return value so a
/// partial sequence survives an error — the caller reports what landed before
/// propagating (#1355).
#[allow(clippy::too_many_arguments)]
pub(crate) async fn execute<P: Provider + Clone>(
    bond: &CapacityBond::CapacityBondInstance<P>,
    provider: P,
    plan: &Plan,
    operator: Address,
    cb_addr: Address,
    mbps: U256,
    outcome: &mut Outcome,
) -> anyhow::Result<()> {
    if plan.shortfall > U256::ZERO {
        let token = Erc20::new(plan.token, provider);
        // Balance check before any send so a doomed run fails clean.
        let balance = token
            .balanceOf(operator)
            .call()
            .await
            .with_context(|| format!("failed to read TOKEN balance from {}", plan.token))?;
        anyhow::ensure!(
            balance >= plan.shortfall,
            "insufficient TOKEN: need {} base units to reach the tier-{} bond, hold {}",
            plan.shortfall,
            plan.mbps,
            balance,
        );

        let allowance = token
            .allowance(operator, cb_addr)
            .call()
            .await
            .with_context(|| format!("failed to read TOKEN allowance from {}", plan.token))?;
        if allowance < plan.shortfall {
            chain_ctx::send(
                token.approve(cb_addr, plan.shortfall),
                "approve",
                None,
                &mut outcome.approve,
            )
            .await?;
        }

        chain_ctx::send(bond.bond(plan.shortfall), "bond", None, &mut outcome.bond).await?;
    }

    if plan.needs_declare {
        // The band is pre-validated in `build_plan`, so this fires only on a
        // mid-run governance change — hence "still", to stop it reading as the
        // first thing to suspect.
        let hint = format!("is {} Mbps still within the capacity band?", plan.mbps);
        chain_ctx::send(
            bond.declareMbps(mbps),
            "declareMbps",
            Some(&hint),
            &mut outcome.declare,
        )
        .await?;
    }

    Ok(())
}

/// Write the plan + outcome as JSON or grep-friendly `key=value` lines. Pure
/// (`&mut impl Write`) so the output shape is unit-testable without a chain.
/// `dry_run` distinguishes a `--dry-run` preview from a real run that was a
/// no-op (already at the target tier) — both submit nothing, but only the
/// former is a dry run.
pub(crate) fn write_plan(
    w: &mut impl io::Write,
    p: &Plan,
    json: bool,
    o: &Outcome,
    dry_run: bool,
) -> io::Result<()> {
    let submitted = o.approve.is_some() || o.bond.is_some() || o.declare.is_some();
    let tx_hex = |h: Option<&B256>| h.map(|v| format!("{v:#x}"));
    if json {
        let value = serde_json::json!({
            "submitted": submitted,
            "dry_run": dry_run,
            "mbps": p.mbps,
            "capacity_bond": format!("{:#x}", p.capacity_bond),
            "token": format!("{:#x}", p.token),
            "bond_required_base": p.required.to_string(),
            "target_bond_base": p.target.to_string(),
            "prior_bond_base": p.prior.to_string(),
            "bonded_base": p.shortfall.to_string(),
            "needs_declare": p.needs_declare,
            "approve_tx": tx_hex(o.approve.as_ref()),
            "bond_tx": tx_hex(o.bond.as_ref()),
            "declare_tx": tx_hex(o.declare.as_ref()),
        });
        return writeln!(w, "{value}");
    }
    // Base units: 1 TOKEN = 1e18 base units.
    writeln!(w, "mbps={}", p.mbps)?;
    writeln!(w, "capacity_bond={:#x}", p.capacity_bond)?;
    writeln!(w, "token={:#x}", p.token)?;
    writeln!(w, "bond_required_base={}", p.required)?;
    writeln!(w, "target_bond_base={}", p.target)?;
    writeln!(w, "prior_bond_base={}", p.prior)?;
    writeln!(w, "bonded_base={}", p.shortfall)?;
    writeln!(w, "needs_declare={}", p.needs_declare)?;
    write_tx_line(w, "approve_tx", o.approve.as_ref())?;
    write_tx_line(w, "bond_tx", o.bond.as_ref())?;
    write_tx_line(w, "declare_tx", o.declare.as_ref())?;
    // A real run already at the target reports `submitted=false dry_run=false`
    // (a genuine no-op), distinct from a `--dry-run` preview.
    writeln!(w, "submitted={submitted} dry_run={dry_run}")
}

/// One `<key>=<tx|skipped>` line.
///
/// `skipped` means "no hash recorded", which since #1355 covers two cases: the
/// step was a genuine no-op (no shortfall, allowance already sufficient, tier
/// already declared), OR the run failed at or before that step — `run` now
/// prints the outcome on the error path too. The exit status and the
/// accompanying stderr error are the discriminator; this line alone is not.
fn write_tx_line(w: &mut impl io::Write, key: &str, tx: Option<&B256>) -> io::Result<()> {
    match tx {
        Some(h) => writeln!(w, "{key}={h:#x}"),
        None => writeln!(w, "{key}=skipped"),
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests;