refactor: use descriptive variable names across crates (#14)

Rename cryptic, comment-dependent, and misleading local bindings,
parameters, and one struct to self-documenting names so the identifier
carries the meaning a comment otherwise would. Behavior-preserving.

- pop: fk->funder_key (signer), c->reconstructed (recovery), v->output
  (chain), d->deposit (db), mult->secs_per_unit and the verify_quote_address
  mint_/our_ hex-comparison locals (mint), Outcome->ExactPaymentTokens (pay),
  misleading ct->change_suffix in two gateway-error messages (error)
- pops-core-funder: eng->hash_engine (script)
- pops-core-verify: premint->pre_mint_secret and bm->blinded_message
  (swap_ceremony); presented/req_json/req->presented_token/requirement_json/
  requirement (wasm)
- pops-gateway: creq_a->encoded_challenge, charge_req->charge_requirement

Author: gudnuf

crates/pop/src/chain.rs

@@ -144,12 +144,12 @@ impl Esplora {
     ) -> Result<(u64, ScriptBuf), Box<dyn std::error::Error>> {
         let vouts = self.tx_vouts(txid).await?;
         let idx = usize::try_from(vout).map_err(|_| "vout does not fit usize")?;
-        let v = vouts
+        let output = vouts
             .get(idx)
             .ok_or_else(|| format!("funding tx has no vout[{vout}]"))?;
-        let bytes = hex::decode(&v.scriptpubkey)
+        let bytes = hex::decode(&output.scriptpubkey)
             .map_err(|e| format!("esplora scriptpubkey hex decode failed: {e}"))?;
-        Ok((v.value, ScriptBuf::from_bytes(bytes)))
+        Ok((output.value, ScriptBuf::from_bytes(bytes)))
     }
 
     /// Lists the UTXOs currently at an address.

crates/pop/src/commands/mint.rs

@@ -629,7 +629,7 @@ fn parse_duration_secs(s: &str) -> Result<u64, Box<dyn std::error::Error>> {
     let n: u64 = num.parse().map_err(|_| {
         PopError::invalid_input(format!("invalid duration `{s}` (expected e.g. 30d, 12h, 45m)"))
     })?;
-    let mult = match unit {
+    let secs_per_unit = match unit {
         "d" | "" => SECS_PER_DAY,
         "h" => 3_600,
         "m" => 60,
@@ -641,7 +641,7 @@ fn parse_duration_secs(s: &str) -> Result<u64, Box<dyn std::error::Error>> {
             .into())
         }
     };
-    n.checked_mul(mult)
+    n.checked_mul(secs_per_unit)
         .ok_or_else(|| PopError::invalid_input(format!("duration `{s}` is too large")).into())
 }
 
@@ -725,34 +725,34 @@ fn verify_quote_address(
         .into());
     }
 
-    if let Some(ik) = &quote.internal_key {
-        let ours = hex::encode(c.internal_key.serialize());
-        if !ik.eq_ignore_ascii_case(&ours) {
+    if let Some(mint_internal_key) = &quote.internal_key {
+        let our_internal_key = hex::encode(c.internal_key.serialize());
+        if !mint_internal_key.eq_ignore_ascii_case(&our_internal_key) {
             return Err(PopError::AddressMismatch {
-                expected: ours,
-                got: ik.clone(),
+                expected: our_internal_key,
+                got: mint_internal_key.clone(),
             }
             .into());
         }
     }
 
-    if let Some(ls) = &quote.leaf_script {
-        let ours = hex::encode(c.leaf_script.as_bytes());
-        if !ls.eq_ignore_ascii_case(&ours) {
+    if let Some(mint_leaf_script) = &quote.leaf_script {
+        let our_leaf_script = hex::encode(c.leaf_script.as_bytes());
+        if !mint_leaf_script.eq_ignore_ascii_case(&our_leaf_script) {
             return Err(PopError::AddressMismatch {
-                expected: ours,
-                got: ls.clone(),
+                expected: our_leaf_script,
+                got: mint_leaf_script.clone(),
             }
             .into());
         }
     }
 
-    if let Some(fp) = &quote.funder_pubkey {
-        let ours = hex::encode(funder_xonly.serialize());
-        if !fp.eq_ignore_ascii_case(&ours) {
+    if let Some(mint_funder_pubkey) = &quote.funder_pubkey {
+        let our_funder_pubkey = hex::encode(funder_xonly.serialize());
+        if !mint_funder_pubkey.eq_ignore_ascii_case(&our_funder_pubkey) {
             return Err(PopError::AddressMismatch {
-                expected: ours,
-                got: fp.clone(),
+                expected: our_funder_pubkey,
+                got: mint_funder_pubkey.clone(),
             }
             .into());
         }

crates/pop/src/commands/pay.rs

@@ -206,7 +206,7 @@ pub async fn run(
         .proofs(&keyset_infos)
         .map_err(|e| PopError::invalid_input(format!("--token proofs are unreadable: {e}")))?;
 
-    let Outcome {
+    let ExactPaymentTokens {
         send_token,
         change_token,
     } = build_exact_payment(
@@ -337,7 +337,7 @@ fn ensure_post_swap_token_bearing(
 }
 
 /// The two tokens produced by the exact-amount construction.
-struct Outcome {
+struct ExactPaymentTokens {
     /// The token worth EXACTLY the charge — this is what is presented.
     send_token: String,
     /// The leftover change token (`None` when the held token equalled the charge).
@@ -358,7 +358,7 @@ async fn build_exact_payment(
     token_total: u64,
     unit: &CurrencyUnit,
     keyset_infos: &[KeySetInfo],
-) -> Result<Outcome, Box<dyn std::error::Error>> {
+) -> Result<ExactPaymentTokens, Box<dyn std::error::Error>> {
     let mint_url_typed = MintUrl::from_str(base)
         .map_err(|e| PopError::invalid_input(format!("mint url `{base}` is invalid: {e}")))?;
 
@@ -381,7 +381,7 @@ async fn build_exact_payment(
             send_proofs_json: Some(send_proofs_json),
             change_proofs_json: None,
         })?;
-        return Ok(Outcome {
+        return Ok(ExactPaymentTokens {
             send_token,
             change_token: None,
         });
@@ -459,7 +459,7 @@ async fn build_exact_payment(
         None => None,
     };
 
-    Ok(Outcome {
+    Ok(ExactPaymentTokens {
         send_token,
         change_token,
     })

crates/pop/src/db.rs

@@ -231,7 +231,7 @@ impl Db {
     /// # Errors
     ///
     /// Propagates SQLite errors (including a duplicate id).
-    pub fn insert_deposit(&self, d: &Deposit) -> Result<(), Box<dyn std::error::Error>> {
+    pub fn insert_deposit(&self, deposit: &Deposit) -> Result<(), Box<dyn std::error::Error>> {
         self.conn
             .execute(
                 r#"INSERT INTO deposits (
@@ -244,26 +244,26 @@ impl Db {
                     ?15, ?16, ?17, ?18, ?19, ?20
                 )"#,
                 params![
-                    d.id,
-                    d.label,
-                    d.mint_url,
-                    d.unit,
-                    d.ts_expiry,
-                    d.amount,
-                    d.funder_index,
-                    d.funder_pubkey,
-                    d.quote_lock_pubkey,
-                    d.p_internal,
-                    d.leaf_script,
-                    d.nonce,
-                    d.mint_pubkey,
-                    d.funding_address,
-                    d.quote_id,
-                    d.state.as_str(),
-                    d.funding_txid,
-                    d.funding_vout,
-                    d.recovery_txid,
-                    d.created_at,
+                    deposit.id,
+                    deposit.label,
+                    deposit.mint_url,
+                    deposit.unit,
+                    deposit.ts_expiry,
+                    deposit.amount,
+                    deposit.funder_index,
+                    deposit.funder_pubkey,
+                    deposit.quote_lock_pubkey,
+                    deposit.p_internal,
+                    deposit.leaf_script,
+                    deposit.nonce,
+                    deposit.mint_pubkey,
+                    deposit.funding_address,
+                    deposit.quote_id,
+                    deposit.state.as_str(),
+                    deposit.funding_txid,
+                    deposit.funding_vout,
+                    deposit.recovery_txid,
+                    deposit.created_at,
                 ],
             )
             .map_err(|e| format!("failed to insert deposit: {e}"))?;

crates/pop/src/error.rs

@@ -736,13 +736,13 @@ impl PopError {
                 change_token,
                 ..
             } => {
-                let ct = match change_token {
+                let change_suffix = match change_token {
                     Some(_) => " plus a change token",
                     None => "",
                 };
                 format!(
                     "the gateway rejected the payment (HTTP {status}): {body}. The gateway did \
-                     NOT redeem, so the send token{ct} are unspent ecash — RECOVER them \
+                     NOT redeem, so the send token{change_suffix} are unspent ecash — RECOVER them \
                      (json: `details.send_token`/`details.change_token`; human mode prints them below)"
                 )
             }
@@ -751,14 +751,14 @@ impl PopError {
                 change_token,
                 ..
             } => {
-                let ct = match change_token {
+                let change_suffix = match change_token {
                     Some(_) => " plus a change token",
                     None => "",
                 };
                 format!(
                     "the payment retry to the gateway failed after the swap already spent the \
                      held proofs ({reason}). The retry never reached the gateway, so the send \
-                     token{ct} are unspent ecash — RECOVER them and present the send token to \
+                     token{change_suffix} are unspent ecash — RECOVER them and present the send token to \
                      the gateway directly; do NOT retry with the original --token (it is spent) \
                      (json: `details.send_token`/`details.change_token`; human mode prints them below)"
                 )

crates/pop/src/recovery.rs

@@ -90,8 +90,12 @@ impl RecoveryFile {
         funder_derivation_path: &str,
         funding_outpoint: Option<&str>,
     ) -> Self {
-        let c = reconstruct(params);
-        let descriptor = descriptor(&c.internal_key, params.ts_expiry, &params.funder_pubkey);
+        let reconstructed = reconstruct(params);
+        let descriptor = descriptor(
+            &reconstructed.internal_key,
+            params.ts_expiry,
+            &params.funder_pubkey,
+        );
         RecoveryFile {
             version: RECOVERY_VERSION.to_string(),
             deposit_id: deposit_id.to_string(),
@@ -105,10 +109,10 @@ impl RecoveryFile {
             funder_pubkey: hex::encode(params.funder_pubkey.serialize()),
             funder_derivation_path: funder_derivation_path.to_string(),
             network: params.network.to_string(),
-            p_internal: hex::encode(c.internal_key.serialize()),
-            leaf_script: hex::encode(c.leaf_script.as_bytes()),
+            p_internal: hex::encode(reconstructed.internal_key.serialize()),
+            leaf_script: hex::encode(reconstructed.leaf_script.as_bytes()),
             descriptor,
-            funding_address: c.address,
+            funding_address: reconstructed.address,
             funding_outpoint: funding_outpoint.map(str::to_string),
             recover_after_utc: utc_iso8601(params.ts_expiry),
             how_to_recover: format!(

crates/pop/src/signer.rs

@@ -110,20 +110,20 @@ impl HotKeySigner {
 impl Signer for HotKeySigner {
     fn funder_pubkey(&self, index: u32) -> Result<FunderPubkey, SignerError> {
         let secp = Secp256k1::new();
-        let fk = derive_funder_key(&self.seed, self.network, index)
+        let funder_key = derive_funder_key(&self.seed, self.network, index)
             .map_err(|e| SignerError::Derivation(e.to_string()))?;
-        let compressed = fk.secret_key.public_key(&secp);
+        let compressed = funder_key.secret_key.public_key(&secp);
         Ok(FunderPubkey {
-            xonly: fk.xonly,
+            xonly: funder_key.xonly,
             compressed,
         })
     }
 
     fn sign(&self, sighash: TapSighash) -> Result<schnorr::Signature, SignerError> {
         let secp = Secp256k1::new();
-        let fk = derive_funder_key(&self.seed, self.network, self.index)
+        let funder_key = derive_funder_key(&self.seed, self.network, self.index)
             .map_err(|e| SignerError::Derivation(e.to_string()))?;
-        let keypair = Keypair::from_secret_key(&secp, &fk.secret_key);
+        let keypair = Keypair::from_secret_key(&secp, &funder_key.secret_key);
         let msg = Message::from_digest(sighash.to_byte_array());
         Ok(secp.sign_schnorr_no_aux_rand(&msg, &keypair))
     }
@@ -135,9 +135,9 @@ impl Signer for HotKeySigner {
     ) -> Result<(), SignerError> {
         // Bridge the funder secret into cdk-common's key type (hex round-trip),
         // NUT-20-sign + self-verify in place.
-        let fk = derive_funder_key(&self.seed, self.network, index)
+        let funder_key = derive_funder_key(&self.seed, self.network, index)
             .map_err(|e| SignerError::Derivation(e.to_string()))?;
-        let funder_secret_hex = Zeroizing::new(hex::encode(fk.secret_key.secret_bytes()));
+        let funder_secret_hex = Zeroizing::new(hex::encode(funder_key.secret_key.secret_bytes()));
         let cdk_secret = cdk_common::SecretKey::from_hex(funder_secret_hex.as_str())
             .map_err(|e| SignerError::Signing(format!("funder secret -> cdk secret: {e}")))?;
         req.sign(cdk_secret.clone())

crates/pops-core-funder/src/script.rs

@@ -57,14 +57,14 @@ pub fn compute_cm(
 ) -> [u8; 32] {
     // Tagged hash: SHA256(SHA256(tag) || SHA256(tag) || msg).
     let tag_hash = sha256::Hash::hash(POP_COMMIT_TAG);
-    let mut eng = sha256::Hash::engine();
-    eng.input(tag_hash.as_ref());
-    eng.input(tag_hash.as_ref());
-    eng.input(mint_pubkey);
-    eng.input(&ts_expiry.to_be_bytes());
-    eng.input(nonce);
-    eng.input(&funder_pubkey.serialize());
-    sha256::Hash::from_engine(eng).to_byte_array()
+    let mut hash_engine = sha256::Hash::engine();
+    hash_engine.input(tag_hash.as_ref());
+    hash_engine.input(tag_hash.as_ref());
+    hash_engine.input(mint_pubkey);
+    hash_engine.input(&ts_expiry.to_be_bytes());
+    hash_engine.input(nonce);
+    hash_engine.input(&funder_pubkey.serialize());
+    sha256::Hash::from_engine(hash_engine).to_byte_array()
 }
 
 /// Computes `P_internal = NUMS_H + cm·G` (`cm` as a scalar mod the curve order,

crates/pops-core-verify/src/swap_ceremony.rs

@@ -53,7 +53,7 @@ fn verify_swap_output_dleq(
         )));
     }
 
-    for (sig, premint) in signatures.iter().zip(pre_mint.secrets.iter()) {
+    for (sig, pre_mint_secret) in signatures.iter().zip(pre_mint.secrets.iter()) {
         // No advertised key for this amount ⇒ the mint signed an amount it never
         // published a key for — reject.
         let key = keys.amount_key(sig.amount).ok_or_else(|| {
@@ -64,7 +64,7 @@ fn verify_swap_output_dleq(
         })?;
 
         // STRICT: both present-but-invalid AND missing reject here.
-        sig.verify_dleq(key, premint.blinded_message.blinded_secret)
+        sig.verify_dleq(key, pre_mint_secret.blinded_message.blinded_secret)
             .map_err(|e| match e {
                 nut12::Error::MissingDleqProof => MintClientError::SwapOutputDleqInvalid(
                     "mint omitted the DLEQ proof on a swap-output blind signature \
@@ -405,36 +405,50 @@ mod tests {
             let last = outputs.len().saturating_sub(1);
 
             let mut signatures = Vec::with_capacity(outputs.len());
-            for (i, bm) in outputs.iter().enumerate() {
-                let k = self.secret_key(bm.amount);
+            for (i, blinded_message) in outputs.iter().enumerate() {
+                let k = self.secret_key(blinded_message.amount);
                 // Correct blind signature C_ = k * B_ in every mode, so the
                 // ONLY thing under test is the DLEQ (not the unblinding).
-                let c = sign_message(&k, &bm.blinded_secret).expect("mock sign_message");
+                let c =
+                    sign_message(&k, &blinded_message.blinded_secret).expect("mock sign_message");
 
                 let attach_valid_dleq = |c: PublicKey, k: &SecretKey| -> BlindSignature {
-                    BlindSignature::new(bm.amount, c, id, &bm.blinded_secret, k.clone())
-                        .expect("mock DLEQ generation")
+                    BlindSignature::new(
+                        blinded_message.amount,
+                        c,
+                        id,
+                        &blinded_message.blinded_secret,
+                        k.clone(),
+                    )
+                    .expect("mock DLEQ generation")
                 };
 
                 let sig = match self.mode {
                     DleqMode::Valid => attach_valid_dleq(c, &k),
                     DleqMode::Missing => BlindSignature {
-                        amount: bm.amount,
+                        amount: blinded_message.amount,
                         keyset_id: id,
                         c,
                         dleq: None,
                     },
                     DleqMode::InvalidWrongKey => {
                         // Correct C_, but the DLEQ is proved against a DIFFERENT
                         // key, so it fails verification against the real key.
-                        let wrong = mint_secret_for_amount(u64::from(bm.amount) + 1000);
-                        BlindSignature::new(bm.amount, c, id, &bm.blinded_secret, wrong)
-                            .expect("mock (wrong-key) DLEQ generation")
+                        let wrong =
+                            mint_secret_for_amount(u64::from(blinded_message.amount) + 1000);
+                        BlindSignature::new(
+                            blinded_message.amount,
+                            c,
+                            id,
+                            &blinded_message.blinded_secret,
+                            wrong,
+                        )
+                        .expect("mock (wrong-key) DLEQ generation")
                     }
                     DleqMode::ValidButOneMissing => {
                         if i == last {
                             BlindSignature {
-                                amount: bm.amount,
+                                amount: blinded_message.amount,
                                 keyset_id: id,
                                 c,
                                 dleq: None,