feat(wallet): on-chain send fee control + BTC/sats amount entry

- sats/BTC unit toggle on the on-chain amount field with live conversion
  hint; canonical value stays sats end-to-end
- Fast / Standard / Slow fee presets (1 / 6 / 144 block targets) plus a
  custom pane taking target blocks or an explicit sat/vB rate
- confirm pane shows LND's fee estimate for the chosen speed via the new
  lnd.estimatefee RPC (GET /v1/transactions/fee)
- lnd.sendcoins now accepts target_conf / sat_per_vbyte with the same
  mutual-exclusion + range validation as channel opens

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

core/archipelago/src/api/rpc/dispatcher.rs

@@ -129,6 +129,7 @@ impl RpcHandler {
             "lnd.closechannel" => self.handle_lnd_closechannel(params).await,
             "lnd.newaddress" => self.handle_lnd_newaddress().await,
             "lnd.sendcoins" => self.handle_lnd_sendcoins(params).await,
+            "lnd.estimatefee" => self.handle_lnd_estimatefee(params).await,
             "lnd.createinvoice" => self.handle_lnd_createinvoice(params).await,
             "lnd.payinvoice" => self.handle_lnd_payinvoice(params).await,
             "lnd.create-psbt" => self.handle_lnd_create_psbt(params).await,

core/archipelago/src/api/rpc/lnd/wallet.rs

@@ -124,16 +124,41 @@ impl RpcHandler {
             return Err(anyhow::anyhow!("Invalid Bitcoin address format"));
         }
 
+        // Fee control: either a confirmation target or an explicit fee rate
+        let target_conf = params.get("target_conf").and_then(|v| v.as_i64());
+        let sat_per_vbyte = params.get("sat_per_vbyte").and_then(|v| v.as_i64());
+        if target_conf.is_some() && sat_per_vbyte.is_some() {
+            return Err(anyhow::anyhow!(
+                "Invalid fee parameters: specify either target_conf or sat_per_vbyte, not both"
+            ));
+        }
+        if let Some(tc) = target_conf {
+            if !(1..=1008).contains(&tc) {
+                return Err(anyhow::anyhow!(
+                    "Invalid target_conf: must be between 1 and 1008 blocks"
+                ));
+            }
+        }
+        if let Some(rate) = sat_per_vbyte {
+            if !(1..=5000).contains(&rate) {
+                return Err(anyhow::anyhow!(
+                    "Invalid sat_per_vbyte: must be between 1 and 5000"
+                ));
+            }
+        }
+
         info!(
             addr = addr,
             amount = amount,
             send_all = send_all,
+            target_conf = target_conf,
+            sat_per_vbyte = sat_per_vbyte,
             "Sending on-chain Bitcoin"
         );
 
         let (client, macaroon_hex) = self.lnd_client().await?;
 
-        let send_body = match amount {
+        let mut send_body = match amount {
             Some(amount) => serde_json::json!({
                 "addr": addr,
                 "amount": amount.to_string(),
@@ -143,6 +168,13 @@ impl RpcHandler {
                 "send_all": true,
             }),
         };
+        if let Some(tc) = target_conf {
+            send_body["target_conf"] = serde_json::json!(tc);
+        }
+        if let Some(rate) = sat_per_vbyte {
+            // LND REST encodes uint64 as a JSON string
+            send_body["sat_per_vbyte"] = serde_json::json!(rate.to_string());
+        }
 
         let resp = client
             .post(format!("{LND_REST_BASE_URL}/v1/transactions"))
@@ -171,6 +203,82 @@ impl RpcHandler {
         Ok(serde_json::json!({ "txid": txid }))
     }
 
+    /// Estimate the on-chain fee for sending `amount` sats to `addr` at a
+    /// confirmation target. Returns `{ fee_sat, sat_per_vbyte }` so the send
+    /// UI can show the cost of each preset before the user confirms.
+    pub(in crate::api::rpc) async fn handle_lnd_estimatefee(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.unwrap_or_default();
+        let addr = params
+            .get("addr")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing 'addr' parameter"))?;
+        if addr.len() < 14 || addr.len() > 90 || !addr.chars().all(|c| c.is_ascii_alphanumeric()) {
+            return Err(anyhow::anyhow!("Invalid Bitcoin address format"));
+        }
+        let amount = params
+            .get("amount")
+            .and_then(|v| v.as_i64())
+            .ok_or_else(|| anyhow::anyhow!("Missing 'amount' parameter (sats)"))?;
+        if !(546..=21_000_000 * 100_000_000).contains(&amount) {
+            return Err(anyhow::anyhow!("Invalid amount"));
+        }
+        let target_conf = params
+            .get("target_conf")
+            .and_then(|v| v.as_i64())
+            .unwrap_or(6);
+        if !(1..=1008).contains(&target_conf) {
+            return Err(anyhow::anyhow!(
+                "Invalid target_conf: must be between 1 and 1008 blocks"
+            ));
+        }
+
+        let (client, macaroon_hex) = self.lnd_client().await?;
+
+        let resp = client
+            .get(format!("{LND_REST_BASE_URL}/v1/transactions/fee"))
+            .query(&[
+                (format!("AddrToAmount[{addr}]"), amount.to_string()),
+                ("target_conf".to_string(), target_conf.to_string()),
+            ])
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await
+            .context("Failed to estimate fee")?;
+
+        let status = resp.status();
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .context("Failed to parse fee estimate response")?;
+
+        if !status.is_success() {
+            let msg = body
+                .get("message")
+                .and_then(|v| v.as_str())
+                .unwrap_or("Unknown error");
+            return Err(anyhow::anyhow!("Failed to estimate fee: {}", msg));
+        }
+
+        // LND REST encodes int64 as JSON strings
+        let fee_sat = body
+            .get("fee_sat")
+            .and_then(|v| v.as_str())
+            .and_then(|s| s.parse::<i64>().ok())
+            .unwrap_or(0);
+        let sat_per_vbyte = body
+            .get("sat_per_vbyte")
+            .and_then(|v| v.as_str())
+            .and_then(|s| s.parse::<i64>().ok())
+            .unwrap_or(0);
+        Ok(serde_json::json!({
+            "fee_sat": fee_sat,
+            "sat_per_vbyte": sat_per_vbyte,
+        }))
+    }
+
     /// Create a Lightning invoice.
     /// Create a Lightning invoice and return `(bolt11, payment_hash_hex)`.
     ///

docs/api-reference.md

@@ -162,7 +162,8 @@ All endpoints use JSON-RPC over HTTP POST to `/rpc/v1`.
 | `lnd.openchannel` | `{ pubkey: string, amount: number }` | `{ funding_txid: string }` | Yes |
 | `lnd.closechannel` | `{ channel_point: string }` | `{ closing_txid: string }` | Yes |
 | `lnd.newaddress` | — | `{ address: string }` | Yes |
-| `lnd.sendcoins` | `{ addr: string, amount: number }` | `{ txid: string }` | Yes |
+| `lnd.sendcoins` | `{ addr: string, amount?: number, send_all?: bool, target_conf?: number, sat_per_vbyte?: number }` | `{ txid: string }` | Yes |
+| `lnd.estimatefee` | `{ addr: string, amount: number, target_conf?: number }` | `{ fee_sat: number, sat_per_vbyte: number }` | Yes |
 | `lnd.createinvoice` | `{ amount: number, memo?: string }` | `{ payment_request: string }` | Yes |
 | `lnd.payinvoice` | `{ payment_request: string }` | `{ preimage: string }` | Yes |
 | `lnd.create-psbt` | `{ outputs: object, ... }` | `{ psbt: string }` | Yes |

neode-ui/mock-backend.js

@@ -3532,6 +3532,13 @@ app.post('/rpc/v1', (req, res) => {
         })
       }
 
+      case 'lnd.estimatefee': {
+        // ~141 vB P2WPKH spend at a rate that scales with urgency
+        const target = params?.target_conf || 6
+        const rate = target <= 1 ? 22 : target <= 6 ? 8 : 2
+        return res.json({ result: { fee_sat: rate * 141, sat_per_vbyte: rate } })
+      }
+
       case 'lnd.decodepayreq': {
         return res.json({
           result: {

neode-ui/src/components/SendBitcoinModal.vue

@@ -78,6 +78,10 @@
               </span>
               <span class="text-sm font-medium text-white/80">−{{ confirmAmount.toLocaleString() }} sats</span>
             </div>
+            <div v-if="effectiveMethod === 'onchain'" class="flex items-center justify-between">
+              <span class="text-xs text-white/50">Network fee</span>
+              <span class="text-sm font-medium text-white/80">{{ feeEstimateLabel }}</span>
+            </div>
             <div class="flex items-center justify-between">
               <span class="text-xs text-white/50">Balance after</span>
               <span class="text-sm font-medium" :class="insufficient ? 'text-red-400' : 'text-white/80'">
@@ -117,7 +121,19 @@
 
         <div class="mb-3">
           <div class="flex items-center justify-between mb-1">
-            <label class="text-white/60 text-sm">{{ t('sendBitcoin.amountSats') }}</label>
+            <div class="flex items-center gap-2">
+              <label class="text-white/60 text-sm">{{ amountLabel }}</label>
+              <!-- sats/BTC entry toggle (on-chain only) -->
+              <div v-if="sendMethod === 'onchain'" class="flex p-0.5 bg-white/5 rounded-md">
+                <button
+                  v-for="u in (['sats', 'btc'] as const)"
+                  :key="u"
+                  @click="setAmountUnit(u)"
+                  class="px-2 py-0.5 rounded text-[11px] font-medium transition-colors"
+                  :class="amountUnit === u ? 'bg-white/15 text-white' : 'text-white/50 hover:text-white/80'"
+                >{{ u === 'btc' ? 'BTC' : 'sats' }}</button>
+              </div>
+            </div>
             <span v-if="pastedInvoiceAmount !== null" class="text-[11px] px-2 py-0.5 rounded-full bg-white/10 text-white/50">set by invoice</span>
             <button
               v-if="sendMethod === 'onchain'"
@@ -131,10 +147,11 @@
             </button>
           </div>
           <input
-            v-model.number="amount"
+            v-model.number="amountEntry"
             type="number"
-            min="1"
-            :placeholder="sendAll ? '' : pastedInvoiceAmount !== null ? '' : '1000'"
+            :min="amountUnit === 'btc' && sendMethod === 'onchain' ? '0.00000001' : '1'"
+            :step="amountUnit === 'btc' && sendMethod === 'onchain' ? '0.00000001' : '1'"
+            :placeholder="sendAll ? '' : pastedInvoiceAmount !== null ? '' : amountUnit === 'btc' && sendMethod === 'onchain' ? '0.001' : '1000'"
             :disabled="sendAll || pastedInvoiceAmount !== null"
             class="w-full input-glass disabled:opacity-50"
           />
@@ -147,6 +164,7 @@
           <p v-else-if="effectiveMethod === 'lightning' && dest.trim()" class="text-xs text-white/50 mt-1">
             Zero-amount invoice — enter how many sats to pay.
           </p>
+          <p v-else-if="unitConversionHint" class="text-xs text-white/40 mt-1">{{ unitConversionHint }}</p>
         </div>
 
         <div v-if="effectiveMethod !== 'ecash'" class="mb-3">
@@ -165,6 +183,48 @@
           <textarea v-model="dest" rows="2" :placeholder="effectiveMethod === 'lightning' ? 'lnbc...' : effectiveMethod === 'ark' ? 'tark1… / lnbc… / user@lnaddress' : 'bc1...'" class="w-full input-glass font-mono"></textarea>
         </div>
 
+        <!-- Network fee (on-chain only) -->
+        <div v-if="sendMethod === 'onchain'" class="mb-3">
+          <label class="text-white/60 text-sm block mb-1">Network fee</label>
+          <div class="flex gap-1 p-1 bg-white/5 rounded-lg">
+            <button
+              v-for="preset in onchainFeePresets"
+              :key="preset.key"
+              @click="feePreset = preset.key"
+              class="flex-1 px-2 py-1.5 rounded text-xs font-medium transition-colors"
+              :class="feePreset === preset.key ? 'bg-white/15 text-white' : 'text-white/50 hover:text-white/80'"
+            >{{ preset.label }}</button>
+          </div>
+          <p v-if="feePreset !== 'custom'" class="text-white/40 text-xs mt-1">
+            {{ onchainFeePresets.find(p => p.key === feePreset)?.hint }}
+          </p>
+          <div v-else class="grid grid-cols-2 gap-3 mt-2">
+            <div>
+              <label class="text-white/60 text-xs block mb-1">Target blocks</label>
+              <input
+                v-model.number="customConfTarget"
+                type="number"
+                min="1"
+                max="1008"
+                placeholder="6"
+                class="w-full input-glass"
+              />
+            </div>
+            <div>
+              <label class="text-white/60 text-xs block mb-1">Sats per vByte</label>
+              <input
+                v-model.number="customSatPerVbyte"
+                type="number"
+                min="1"
+                max="5000"
+                placeholder="—"
+                class="w-full input-glass"
+              />
+            </div>
+            <p class="text-white/40 text-xs col-span-2">Set one — sats per vByte takes precedence when both are set</p>
+          </div>
+        </div>
+
         <div v-if="ecashToken" class="mb-3 p-2 bg-white/5 rounded-lg">
           <p class="text-white/50 text-xs mb-1">{{ t('sendBitcoin.tokenShareLabel') }}</p>
           <!-- QR so the recipient can scan the token straight off this screen
@@ -208,7 +268,47 @@ const emit = defineEmits<{ close: []; sent: []; scan: [] }>()
 // 'auto' remains in the type for the effectiveMethod logic but is no longer
 // offered as a tab (hidden per operator request 2026-07-22).
 const sendMethod = ref<'auto' | 'lightning' | 'onchain' | 'ecash' | 'fedimint' | 'ark'>('lightning')
-const amount = ref<number>(0)
+
+// --- Amount entry with a sats/BTC unit toggle (on-chain). `amountEntry` is
+// --- what the user types in the chosen unit; `amount` stays the canonical
+// --- sats value the rest of the flow reads and writes.
+const amountUnit = ref<'sats' | 'btc'>('sats')
+const amountEntry = ref<number>(0)
+const amount = computed<number>({
+  get: () =>
+    amountUnit.value === 'btc'
+      ? Math.round((amountEntry.value || 0) * 100_000_000)
+      : Math.floor(amountEntry.value || 0),
+  set: (sats: number) => {
+    amountEntry.value = amountUnit.value === 'btc' ? (sats || 0) / 100_000_000 : sats || 0
+  },
+})
+
+/** Switch entry unit, converting whatever is already typed. */
+function setAmountUnit(unit: 'sats' | 'btc') {
+  if (unit === amountUnit.value) return
+  const sats = amount.value
+  amountUnit.value = unit
+  amount.value = sats
+}
+
+// Only the on-chain tab offers BTC entry — leaving it snaps back to sats so
+// the lightning/ecash flows (and their sats-only hints) stay consistent.
+watch(sendMethod, (m) => {
+  if (m !== 'onchain' && amountUnit.value !== 'sats') setAmountUnit('sats')
+})
+
+const amountLabel = computed(() =>
+  sendMethod.value === 'onchain' && amountUnit.value === 'btc' ? 'Amount (BTC)' : t('sendBitcoin.amountSats')
+)
+
+const unitConversionHint = computed(() => {
+  if (sendMethod.value !== 'onchain' || !amountEntry.value) return ''
+  return amountUnit.value === 'btc'
+    ? `= ${amount.value.toLocaleString()} sats`
+    : `= ${(amount.value / 100_000_000).toFixed(8).replace(/0+$/, '').replace(/\.$/, '')} BTC`
+})
+
 const dest = ref('')
 const processing = ref(false)
 const error = ref('')
@@ -248,6 +348,78 @@ function toggleSendAll() {
 // Leaving the on-chain tab disarms the sweep so it can never apply elsewhere
 watch(sendMethod, (m) => { if (m !== 'onchain') sendAll.value = false })
 
+// --- On-chain network fee: presets map to LND confirmation targets; custom
+// --- takes a block target or an explicit sat/vB rate (rate wins).
+type OnchainFeePreset = 'fast' | 'standard' | 'slow' | 'custom'
+
+const onchainFeePresets: { key: OnchainFeePreset; label: string; hint?: string; confTarget?: number }[] = [
+  { key: 'fast', label: 'Fast', hint: 'Targets the next block (~10 minutes)', confTarget: 1 },
+  { key: 'standard', label: 'Standard', hint: 'Confirms within ~6 blocks (about an hour)', confTarget: 6 },
+  { key: 'slow', label: 'Slow', hint: 'Confirms within ~144 blocks (about a day)', confTarget: 144 },
+  { key: 'custom', label: 'Custom' },
+]
+
+const feePreset = ref<OnchainFeePreset>('standard')
+const customConfTarget = ref<number | null>(null)
+const customSatPerVbyte = ref<number | null>(null)
+// Resolved at review time so confirm + send use the same params.
+const resolvedFeeParams = ref<{ target_conf?: number; sat_per_vbyte?: number }>({})
+
+function onchainFeeParams(): { target_conf?: number; sat_per_vbyte?: number } | null {
+  if (feePreset.value !== 'custom') {
+    return { target_conf: onchainFeePresets.find(p => p.key === feePreset.value)?.confTarget ?? 6 }
+  }
+  const rate = customSatPerVbyte.value
+  const conf = customConfTarget.value
+  if (rate != null && rate !== 0) {
+    if (rate < 1 || rate > 5000) { error.value = 'Sats per vByte must be between 1 and 5000'; return null }
+    return { sat_per_vbyte: Math.floor(rate) }
+  }
+  if (conf != null && conf !== 0) {
+    if (conf < 1 || conf > 1008) { error.value = 'Target blocks must be between 1 and 1008'; return null }
+    return { target_conf: Math.floor(conf) }
+  }
+  error.value = 'Custom fee requires target blocks or sats per vByte'
+  return null
+}
+
+// Fee estimate for the confirm pane (best-effort — LND's own estimator).
+const feeEstimate = ref<{ fee_sat: number; sat_per_vbyte: number } | null>(null)
+const feeEstimateLoading = ref(false)
+
+const feeEstimateLabel = computed(() => {
+  if (feeEstimate.value) {
+    return `~${feeEstimate.value.fee_sat.toLocaleString()} sats · ${feeEstimate.value.sat_per_vbyte} sat/vB`
+  }
+  if (resolvedFeeParams.value.sat_per_vbyte) {
+    return `${resolvedFeeParams.value.sat_per_vbyte} sat/vB (custom)`
+  }
+  if (feeEstimateLoading.value) return '…'
+  return isSweep.value ? 'deducted from swept amount' : 'estimated at broadcast'
+})
+
+async function loadFeeEstimate() {
+  feeEstimate.value = null
+  // Explicit sat/vB shows as-is; sweeps have no fixed amount to estimate on.
+  if (resolvedFeeParams.value.sat_per_vbyte || isSweep.value) return
+  const addr = dest.value.trim()
+  const amt = confirmAmount.value
+  if (!addr || amt < 546) return
+  feeEstimateLoading.value = true
+  try {
+    const res = await rpcClient.call<{ fee_sat: number; sat_per_vbyte: number }>({
+      method: 'lnd.estimatefee',
+      params: { addr, amount: amt, target_conf: resolvedFeeParams.value.target_conf ?? 6 },
+      timeout: 10000,
+    })
+    if (res.fee_sat > 0) feeEstimate.value = res
+  } catch {
+    /* estimate is a preview — the label falls back to prose */
+  } finally {
+    feeEstimateLoading.value = false
+  }
+}
+
 // Clipboard read needs a secure context (or the companion bridge); hide the
 // button where it can't work — the textarea still accepts a manual paste.
 const canReadClipboard = typeof navigator !== 'undefined' && !!navigator.clipboard?.readText
@@ -367,6 +539,15 @@ function review() {
   if (!isSweep.value && confirmAmount.value <= 0 && invoiceAmountSats.value === null) {
     error.value = t('sendBitcoin.amountSats'); return
   }
+  if (method === 'onchain') {
+    const fee = onchainFeeParams()
+    if (!fee) return
+    resolvedFeeParams.value = fee
+    void loadFeeEstimate()
+  } else {
+    resolvedFeeParams.value = {}
+    feeEstimate.value = null
+  }
   void loadConfirmBalance()
   confirming.value = true
 }
@@ -449,8 +630,8 @@ async function send() {
       const res = await rpcClient.call<{ txid: string }>({
         method: 'lnd.sendcoins',
         params: isSweep.value
-          ? { addr: dest.value.trim(), send_all: true }
-          : { addr: dest.value.trim(), amount: amount.value },
+          ? { addr: dest.value.trim(), send_all: true, ...resolvedFeeParams.value }
+          : { addr: dest.value.trim(), amount: amount.value, ...resolvedFeeParams.value },
       })
       successInfo.value = {
         amount: paidAmount,