fedimint_lnv2_client/

cli.rs

use std::path::{Path, PathBuf};
use std::{ffi, iter};

use bitcoin::hashes::sha256;
use bitcoin::secp256k1;
use clap::{Parser, Subcommand};
use fedimint_api_client::api::FederationError;
use fedimint_client_module::error::OperationLookupError;
use fedimint_core::core::OperationId;
use fedimint_core::util::SafeUrl;
use fedimint_core::{Amount, OutPoint, PeerId, TransactionId, hex};
use fedimint_lnv2_common::contracts::{OutgoingContract, PaymentImage};
use lightning_invoice::Bolt11Invoice;
use secp256k1::schnorr::Signature;
use secp256k1::{Keypair, PublicKey, SecretKey};
use serde::Serialize;
use serde_json::Value;

use crate::api::LightningFederationApi;
use crate::{
    Bolt11InvoiceDescription, GenerateLnurlError, LightningClientModule, ListGatewaysError,
    ReceiveError, SelectGatewayError, SendPaymentError,
};

#[cfg(test)]
mod tests;

#[derive(Parser, Serialize)]
enum Opts {
    /// Pay an invoice. For  testing  you can optionally specify a gateway to
    /// route with, otherwise a gateway will be selected automatically.
    Send {
        invoice: Bolt11Invoice,
        #[arg(long)]
        gateway: Option<SafeUrl>,
    },
    /// Await the final state of the send operation.
    AwaitSend { operation_id: OperationId },
    /// Request an invoice. For testing you can optionally specify a gateway to
    /// generate the invoice, otherwise a gateway will be selected
    /// automatically.
    Receive {
        amount: Amount,
        #[arg(long)]
        gateway: Option<SafeUrl>,
    },
    /// Await the final state of the receive operation.
    AwaitReceive { operation_id: OperationId },
    /// Lnurl subcommands
    #[command(subcommand)]
    Lnurl(LnurlOpts),
    /// Gateway subcommands
    #[command(subcommand)]
    Gateways(GatewaysOpts),
    /// Direct HTLC subcommands to swap with a counterparty in the same
    /// federation without a gateway
    #[command(subcommand)]
    Htlc(HtlcOpts),
}

#[derive(Clone, Subcommand, Serialize)]
enum HtlcOpts {
    /// Fund an HTLC locked to the counterparty's claim public key. Requires
    /// exactly one of --payment-hash and --payment-point.
    Create {
        amount: Amount,
        claim_pk: PublicKey,
        expiration_delta: u64,
        #[arg(long)]
        payment_hash: Option<sha256::Hash>,
        #[arg(long)]
        payment_point: Option<PublicKey>,
    },
    /// Generate a random claim keypair to receive an HTLC with. The secret key
    /// is written as hex to a new file created with owner-only permissions and
    /// only the public key is printed.
    NewClaimKeypair {
        /// Path of the new file to write the secret key to. An existing file is
        /// never overwritten.
        #[arg(long)]
        secret_key_file: PathBuf,
    },
    /// Wait until the contract is funded at the outpoint and print the number
    /// of blocks remaining until its expiration.
    AwaitFunded {
        funding_txid: TransactionId,
        #[arg(long, default_value_t = 0)]
        out_idx: u64,
        contract: String,
    },
    /// Claim a funded HTLC with the preimage of its payment image.
    Claim {
        funding_txid: TransactionId,
        #[arg(long, default_value_t = 0)]
        out_idx: u64,
        contract: String,
        /// Read the hex claim secret key from a file, or '-' for stdin.
        #[arg(long)]
        claim_sk_file: PathBuf,
        /// Read the hex preimage from a file, or '-' for stdin.
        #[arg(long)]
        preimage_file: PathBuf,
    },
    /// Create a forfeit signature to fail an HTLC locked to our claim key
    /// cooperatively.
    Forfeit {
        contract: String,
        /// Read the hex claim secret key from a file, or '-' for stdin.
        #[arg(long)]
        claim_sk_file: PathBuf,
    },
    /// Cancel an HTLC we created before its expiration with the
    /// counterparty's forfeit signature.
    Cancel {
        funding_txid: TransactionId,
        #[arg(long, default_value_t = 0)]
        out_idx: u64,
        contract: String,
        forfeit_signature: Signature,
    },
    /// Refund an HTLC we created after its expiration.
    Refund {
        funding_txid: TransactionId,
        #[arg(long, default_value_t = 0)]
        out_idx: u64,
        contract: String,
    },
    /// Wait until an HTLC we created is claimed, printing the preimage, or
    /// expired unclaimed, printing null.
    AwaitResolution {
        funding_txid: TransactionId,
        #[arg(long, default_value_t = 0)]
        out_idx: u64,
        contract: String,
    },
    /// Wait until the transaction of an HTLC operation is accepted and any
    /// ecash it issues has been minted.
    AwaitSettled { operation_id: OperationId },
}

#[derive(Clone, Subcommand, Serialize)]
enum LnurlOpts {
    /// Generate a new lnurl.
    Generate {
        recurringd: SafeUrl,
        #[arg(long)]
        gateway: Option<SafeUrl>,
    },
}

#[derive(Clone, Subcommand, Serialize)]
enum GatewaysOpts {
    /// Update the mapping from lightning node public keys to gateway api
    /// endpoints maintained in the module database to optimise gateway
    /// selection for a given invoice; this command is intended for testing.
    Map,
    /// Select an online vetted gateway; this command is intended for testing.
    Select {
        #[arg(long)]
        invoice: Option<Bolt11Invoice>,
    },
    /// List all vetted gateways.
    List {
        #[arg(long)]
        peer: Option<PeerId>,
    },
    /// Add a vetted gateway.
    Add { gateway: SafeUrl },
    /// Remove a vetted gateway.
    Remove { gateway: SafeUrl },
}

pub(crate) async fn handle_cli_command(
    lightning: &LightningClientModule,
    args: &[ffi::OsString],
) -> Result<serde_json::Value, CliCommandError> {
    let opts = Opts::parse_from(iter::once(&ffi::OsString::from("lnv2")).chain(args.iter()));

    let value = match opts {
        Opts::Send { gateway, invoice } => {
            json(lightning.send(invoice, gateway, Value::Null).await?)
        }
        Opts::AwaitSend { operation_id } => json(
            lightning
                .await_final_send_operation_state(operation_id)
                .await?,
        ),
        Opts::Receive { amount, gateway } => json(
            lightning
                .receive(
                    amount,
                    3600,
                    Bolt11InvoiceDescription::Direct(String::new()),
                    gateway,
                    Value::Null,
                )
                .await?,
        ),
        Opts::AwaitReceive { operation_id } => json(
            lightning
                .await_final_receive_operation_state(operation_id)
                .await?,
        ),
        Opts::Lnurl(lnurl_opts) => match lnurl_opts {
            LnurlOpts::Generate {
                recurringd,
                gateway,
            } => json(lightning.generate_lnurl(recurringd, gateway).await?),
        },
        Opts::Gateways(gateway_opts) => match gateway_opts {
            #[allow(clippy::unit_arg)]
            GatewaysOpts::Map => json(lightning.update_gateway_map().await),
            GatewaysOpts::Select { invoice } => json(lightning.select_gateway(invoice).await?.0),
            GatewaysOpts::List { peer } => json(lightning.list_gateways(peer).await?),
            GatewaysOpts::Add { gateway } => {
                let auth = lightning
                    .admin_auth
                    .clone()
                    .ok_or(CliCommandError::AdminAuthNotSet)?;

                json(lightning.module_api.add_gateway(auth, gateway).await?)
            }
            GatewaysOpts::Remove { gateway } => {
                let auth = lightning
                    .admin_auth
                    .clone()
                    .ok_or(CliCommandError::AdminAuthNotSet)?;

                json(lightning.module_api.remove_gateway(auth, gateway).await?)
            }
        },
        Opts::Htlc(htlc_opts) => handle_htlc_command(lightning, htlc_opts).await?,
    };

    Ok(value)
}

#[allow(clippy::too_many_lines)]
async fn handle_htlc_command(
    lightning: &LightningClientModule,
    htlc_opts: HtlcOpts,
) -> Result<Value, CliCommandError> {
    let value = match htlc_opts {
        HtlcOpts::Create {
            amount,
            claim_pk,
            expiration_delta,
            payment_hash,
            payment_point,
        } => {
            let payment_image = match (payment_hash, payment_point) {
                (Some(hash), None) => PaymentImage::Hash(hash),
                (None, Some(point)) => PaymentImage::Point(point),
                _ => return Err(CliCommandError::InvalidPaymentImage),
            };

            let (operation_id, outpoint, contract) = lightning
                .create_htlc(
                    amount,
                    payment_image,
                    claim_pk,
                    expiration_delta,
                    Value::Null,
                )
                .await?;

            json(serde_json::json!({
                "operation_id": operation_id,
                "outpoint": outpoint,
                "contract": contract,
            }))
        }
        HtlcOpts::NewClaimKeypair { secret_key_file } => {
            let keypair = Keypair::new(secp256k1::SECP256K1, &mut rand::thread_rng());

            write_secret_key_file(&secret_key_file, &keypair.secret_key())?;

            json(serde_json::json!({
                "public_key": keypair.public_key(),
            }))
        }
        HtlcOpts::AwaitFunded {
            funding_txid,
            out_idx,
            contract,
        } => json(
            lightning
                .await_htlc_funded(outpoint(funding_txid, out_idx), &parse_contract(&contract)?)
                .await?,
        ),
        HtlcOpts::Claim {
            funding_txid,
            out_idx,
            contract,
            claim_sk_file,
            preimage_file,
        } => {
            let contract = parse_contract(&contract)?;

            ensure_single_stdin(&claim_sk_file, &preimage_file)?;

            let claim_sk = read_claim_sk(&claim_sk_file)?;
            let preimage = read_preimage(&preimage_file)?;

            json(
                lightning
                    .claim_htlc(
                        outpoint(funding_txid, out_idx),
                        contract,
                        claim_sk.keypair(secp256k1::SECP256K1),
                        preimage,
                        Value::Null,
                    )
                    .await?,
            )
        }
        HtlcOpts::Forfeit {
            contract,
            claim_sk_file,
        } => {
            let contract = parse_contract(&contract)?;
            let claim_sk = read_claim_sk(&claim_sk_file)?;

            json(LightningClientModule::create_htlc_forfeit_signature(
                &contract,
                &claim_sk.keypair(secp256k1::SECP256K1),
            )?)
        }
        HtlcOpts::Cancel {
            funding_txid,
            out_idx,
            contract,
            forfeit_signature,
        } => json(
            lightning
                .cancel_htlc(
                    outpoint(funding_txid, out_idx),
                    parse_contract(&contract)?,
                    forfeit_signature,
                    Value::Null,
                )
                .await?,
        ),
        HtlcOpts::Refund {
            funding_txid,
            out_idx,
            contract,
        } => json(
            lightning
                .refund_htlc(
                    outpoint(funding_txid, out_idx),
                    parse_contract(&contract)?,
                    Value::Null,
                )
                .await?,
        ),
        HtlcOpts::AwaitResolution {
            funding_txid,
            out_idx,
            contract,
        } => json(
            lightning
                .await_htlc_resolution(outpoint(funding_txid, out_idx), &parse_contract(&contract)?)
                .await?
                .map(hex::encode),
        ),
        HtlcOpts::AwaitSettled { operation_id } => {
            lightning.await_htlc_operation_settled(operation_id).await?;

            json("settled")
        }
    };

    Ok(value)
}

fn outpoint(txid: TransactionId, out_idx: u64) -> OutPoint {
    OutPoint { txid, out_idx }
}

fn parse_contract(contract: &str) -> Result<OutgoingContract, CliCommandError> {
    serde_json::from_str(contract).map_err(CliCommandError::InvalidContract)
}

/// The longest secret input we accept: 64 hex characters plus a line ending.
const MAX_SECRET_HEX_BYTES: usize = 66;

fn read_claim_sk(path: &Path) -> Result<SecretKey, CliCommandError> {
    let claim_sk = read_secret_hex(path)?;

    // Neither the input nor the parse error may appear in diagnostics.
    claim_sk
        .parse()
        .map_err(|_| CliCommandError::InvalidClaimSecretKey)
}

fn read_preimage(path: &Path) -> Result<[u8; 32], CliCommandError> {
    let preimage = read_secret_hex(path)?;

    <[u8; 32]>::try_from(hex::decode(preimage).map_err(|_| CliCommandError::InvalidPreimageHex)?)
        .map_err(|_| CliCommandError::InvalidPreimageLength)
}

fn ensure_single_stdin(first: &Path, second: &Path) -> Result<(), CliCommandError> {
    #[cfg(not(target_family = "wasm"))]
    fedimint_core::util::ensure_single_stdin([first, second])?;

    #[cfg(target_family = "wasm")]
    let _ = (first, second);

    Ok(())
}

fn read_secret_hex(path: &Path) -> Result<String, CliCommandError> {
    #[cfg(not(target_family = "wasm"))]
    {
        Ok(fedimint_core::util::read_secret_file(
            path,
            MAX_SECRET_HEX_BYTES,
        )?)
    }

    #[cfg(target_family = "wasm")]
    {
        let _ = path;

        Err(CliCommandError::UnsupportedSecretInput)
    }
}

/// Write the secret key as hex to a new file only its owner can read.
fn write_secret_key_file(path: &Path, secret_key: &SecretKey) -> Result<(), CliCommandError> {
    #[cfg(not(target_family = "wasm"))]
    {
        use std::io::Write as _;

        let mut options = std::fs::OpenOptions::new();

        options.write(true).create_new(true);

        #[cfg(unix)]
        std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);

        let mut file = options
            .open(path)
            .map_err(CliCommandError::SecretKeyFileCreate)?;

        writeln!(file, "{}", secret_key.display_secret())
            .and_then(|()| file.sync_all())
            .map_err(|_| CliCommandError::SecretKeyFileWrite)
    }

    #[cfg(target_family = "wasm")]
    {
        let _ = (path, secret_key);

        Err(CliCommandError::UnsupportedSecretInput)
    }
}

fn json<T: Serialize>(value: T) -> Value {
    serde_json::to_value(value).expect("JSON serialization failed")
}

/// A failure of an `lnv2` module command.
#[derive(Debug, thiserror::Error)]
pub(crate) enum CliCommandError {
    /// The direct HTLC operation failed.
    #[error(transparent)]
    Htlc(#[from] crate::htlc::HtlcError),

    /// Exactly one payment image must be specified.
    #[error("Specify exactly one of --payment-hash and --payment-point")]
    InvalidPaymentImage,

    /// The supplied contract was not valid JSON.
    #[error("Failed to parse the contract JSON: {0}")]
    InvalidContract(#[source] serde_json::Error),

    /// A secret input file could not be read.
    #[cfg(not(target_family = "wasm"))]
    #[error(transparent)]
    SecretInput(#[from] fedimint_core::util::SecretInputError),

    /// Secret input files are not supported on this platform.
    #[cfg(target_family = "wasm")]
    #[error("Secret input files are not supported on this platform")]
    UnsupportedSecretInput,

    /// The claim secret key file could not be created.
    #[error("Could not create the secret key file: {0}")]
    SecretKeyFileCreate(#[source] std::io::Error),

    /// The claim secret key could not be written to its file.
    #[error("Could not write the secret key file")]
    SecretKeyFileWrite,

    /// The supplied claim secret key was not a valid hex secret key.
    #[error("The claim secret key is not a valid hex secret key")]
    InvalidClaimSecretKey,

    /// The supplied preimage was not valid hexadecimal.
    #[error("The preimage is not valid hex")]
    InvalidPreimageHex,

    /// The supplied preimage had the wrong length.
    #[error("The preimage must be exactly 32 bytes")]
    InvalidPreimageLength,

    /// The payment could not be started.
    #[error(transparent)]
    Send(#[from] SendPaymentError),

    /// The operation to await could not be looked up.
    #[error(transparent)]
    OperationLookup(#[from] OperationLookupError),

    /// The invoice could not be created.
    #[error(transparent)]
    Receive(#[from] ReceiveError),

    /// The LNURL could not be generated.
    #[error(transparent)]
    GenerateLnurl(#[from] GenerateLnurlError),

    /// No gateway could be selected.
    #[error(transparent)]
    SelectGateway(#[from] SelectGatewayError),

    /// The vetted gateways could not be listed.
    #[error(transparent)]
    ListGateways(#[from] ListGatewaysError),

    /// The federation did not serve an admin request.
    #[error(transparent)]
    Federation(#[from] FederationError),

    /// The client has no admin credentials, which adding or removing a vetted
    /// gateway needs.
    #[error("Admin auth not set")]
    AdminAuthNotSet,
}