Skip to content

Expose idempotency keys for operations which allow them. #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 12, 2025
Merged

Expose idempotency keys for operations which allow them. #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 30 additions & 6 deletions lightspark-sdk/src/commonJvmAndroidMain/kotlin/com/lightspark/sdk/LightsparkFuturesClient.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,8 @@ class LightsparkFuturesClient(config: ClientConfig) {
* for a transaction between 10k sats and 100k sats, this would mean a fee limit of 15 to 150 sats.
* @param amountMsats The amount to pay in milli-satoshis. Defaults to the full amount of the invoice.
* @param timeoutSecs The number of seconds to wait for the payment to complete. Defaults to 60.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return The payment details.
*/
@JvmOverloads
Expand All @@ -231,6 +233,7 @@ class LightsparkFuturesClient(config: ClientConfig) {
maxFeesMsats: Long,
amountMsats: Long? = null,
timeoutSecs: Int = 60,
idempotencyKey: String? = null,
): CompletableFuture<OutgoingPayment> =
coroutineScope.future {
coroutinesClient.payInvoice(
Expand All @@ -239,6 +242,7 @@ class LightsparkFuturesClient(config: ClientConfig) {
maxFeesMsats,
amountMsats,
timeoutSecs,
idempotencyKey,
)
}

Expand All @@ -257,6 +261,8 @@ class LightsparkFuturesClient(config: ClientConfig) {
* @param signingPrivateKey The sender's signing private key. Used to hash the sender identifier.
* @param senderIdentifier Optional identifier of the sender. If provided, this will be hashed using a
* monthly-rotated seed and used for anonymized analysis.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return The payment details.
*/
@JvmOverloads
Expand All @@ -269,6 +275,7 @@ class LightsparkFuturesClient(config: ClientConfig) {
timeoutSecs: Int = 60,
signingPrivateKey: ByteArray? = null,
senderIdentifier: String? = null,
idempotencyKey: String? = null,
): CompletableFuture<OutgoingPayment> =
coroutineScope.future {
coroutinesClient.payUmaInvoice(
Expand All @@ -279,6 +286,7 @@ class LightsparkFuturesClient(config: ClientConfig) {
timeoutSecs,
signingPrivateKey,
senderIdentifier,
idempotencyKey,
)
}

Expand Down Expand Up @@ -432,14 +440,26 @@ class LightsparkFuturesClient(config: ClientConfig) {
* @param amountSats The amount of funds to withdraw in SATOSHI.
* @param bitcoinAddress The Bitcoin address to withdraw funds to.
* @param mode The mode to use for the withdrawal. See `WithdrawalMode` for more information.
* @param idempotencyKey An optional key to ensure idempotency of the withdrawal. If provided, the same result will
* be returned for the same idempotency key without triggering a new withdrawal.
*/
@JvmOverloads
fun requestWithdrawal(
nodeId: String,
amountSats: Long,
bitcoinAddress: String,
mode: WithdrawalMode,
idempotencyKey: String? = null,
): CompletableFuture<WithdrawalRequest> =
coroutineScope.future { coroutinesClient.requestWithdrawal(nodeId, amountSats, bitcoinAddress, mode) }
coroutineScope.future {
coroutinesClient.requestWithdrawal(
nodeId,
amountSats,
bitcoinAddress,
mode,
idempotencyKey,
)
}

/**
* Sends a payment directly to a node on the Lightning Network through the public key of the node without an invoice.
Expand All @@ -451,6 +471,8 @@ class LightsparkFuturesClient(config: ClientConfig) {
* As guidance, a maximum fee of 15 basis points should make almost all transactions succeed. For example,
* for a transaction between 10k sats and 100k sats, this would mean a fee limit of 15 to 150 sats.
* @param timeoutSecs The timeout in seconds that we will try to make the payment.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return An `OutgoingPayment` object if the payment was successful, or throws if the payment failed.
* @throws LightsparkException if the payment failed.
*/
Expand All @@ -461,13 +483,15 @@ class LightsparkFuturesClient(config: ClientConfig) {
amountMsats: Long,
maxFeesMsats: Long,
timeoutSecs: Int = 60,
idempotencyKey: String? = null,
): CompletableFuture<OutgoingPayment> = coroutineScope.future {
coroutinesClient.sendPayment(
payerNodeId,
destinationPublicKey,
amountMsats,
maxFeesMsats,
timeoutSecs,
idempotencyKey,
)
}

Expand Down Expand Up @@ -579,27 +603,27 @@ class LightsparkFuturesClient(config: ClientConfig) {

/**
* fetch outgoing payments for a given payment hash
*
*
* @param paymentHash the payment hash of the invoice for which to fetch the outgoing payments
* @param transactionStatuses the transaction statuses to filter the payments by. If null, all payments will be returned.
*/
@Throws(LightsparkException::class, LightsparkAuthenticationException::class)
fun getOutgoingPaymentsForPaymentHash(
paymentHash: String,
transactionStatuses: List<TransactionStatus>? = null
transactionStatuses: List<TransactionStatus>? = null,
): CompletableFuture<List<OutgoingPayment>> = coroutineScope.future {
coroutinesClient.getOutgoingPaymentForPaymentHash(paymentHash, transactionStatuses)
}

/**
* fetch invoice for a given payments hash
*
*
* @param paymentHash the payment hash of the invoice for which to fetch the outgoing payments
* @param transactionStatuses the transaction statuses to filter the payments by. If null, all payments will be returned.
*/
@Throws(LightsparkException::class, LightsparkAuthenticationException::class)
fun getInvoiceForPaymentHash(
paymentHash: String
paymentHash: String,
): CompletableFuture<Invoice> = coroutineScope.future {
coroutinesClient.getInvoiceForPaymentHash(paymentHash)
}
Expand All @@ -623,7 +647,7 @@ class LightsparkFuturesClient(config: ClientConfig) {
@Throws(LightsparkException::class, LightsparkAuthenticationException::class)
fun getIncomingPaymentsForInvoice(
invoiceId: String,
transactionStatuses: List<TransactionStatus>? = null
transactionStatuses: List<TransactionStatus>? = null,
): CompletableFuture<List<IncomingPayment>> = coroutineScope.future {
coroutinesClient.getIncomingPaymentsForInvoice(invoiceId, transactionStatuses)
}
Expand Down
18 changes: 18 additions & 0 deletions lightspark-sdk/src/commonMain/kotlin/com/lightspark/sdk/LightsparkCoroutinesClient.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,6 +347,8 @@ class LightsparkCoroutinesClient private constructor(
* for a transaction between 10k sats and 100k sats, this would mean a fee limit of 15 to 150 sats.
* @param amountMsats The amount to pay in milli-satoshis. Defaults to the full amount of the invoice.
* @param timeoutSecs The number of seconds to wait for the payment to complete. Defaults to 60.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return The payment details.
*/
@JvmOverloads
Expand All @@ -356,6 +358,7 @@ class LightsparkCoroutinesClient private constructor(
maxFeesMsats: Long,
amountMsats: Long? = null,
timeoutSecs: Int = 60,
idempotencyKey: String? = null,
): OutgoingPayment {
requireValidAuth()
return executeQuery(
Expand All @@ -367,6 +370,7 @@ class LightsparkCoroutinesClient private constructor(
add("timeout_secs", timeoutSecs)
add("maximum_fees_msats", maxFeesMsats)
amountMsats?.let { add("amount_msats", amountMsats) }
idempotencyKey?.let { add("idempotency_key", idempotencyKey) }
},
signingNodeId = nodeId,
) {
Expand All @@ -392,6 +396,8 @@ class LightsparkCoroutinesClient private constructor(
* @param signingPrivateKey The sender's signing private key. Used to hash the sender identifier.
* @param senderIdentifier Optional identifier of the sender. If provided, this will be hashed using a
* monthly-rotated seed and used for anonymized analysis.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return The payment details.
*/
@JvmOverloads
Expand All @@ -404,6 +410,7 @@ class LightsparkCoroutinesClient private constructor(
timeoutSecs: Int = 60,
signingPrivateKey: ByteArray? = null,
senderIdentifier: String? = null,
idempotencyKey: String? = null,
): OutgoingPayment {
requireValidAuth()

Expand All @@ -425,6 +432,7 @@ class LightsparkCoroutinesClient private constructor(
add("maximum_fees_msats", maxFeesMsats)
amountMsats?.let { add("amount_msats", amountMsats) }
senderHash?.let { add("sender_hash", senderHash) }
idempotencyKey?.let { add("idempotency_key", idempotencyKey) }
},
signingNodeId = nodeId,
) {
Expand Down Expand Up @@ -767,12 +775,16 @@ class LightsparkCoroutinesClient private constructor(
* @param amountSats The amount of funds to withdraw in SATOSHI.
* @param bitcoinAddress The Bitcoin address to withdraw funds to.
* @param mode The mode to use for the withdrawal. See `WithdrawalMode` for more information.
* @param idempotencyKey An optional key to ensure idempotency of the withdrawal. If provided, the same result will
* be returned for the same idempotency key without triggering a new withdrawal.
*/
@JvmOverloads
suspend fun requestWithdrawal(
nodeId: String,
amountSats: Long,
bitcoinAddress: String,
mode: WithdrawalMode,
idempotencyKey: String? = null,
): WithdrawalRequest {
requireValidAuth()
return executeQuery(
Expand All @@ -783,6 +795,7 @@ class LightsparkCoroutinesClient private constructor(
add("amount_sats", amountSats)
add("bitcoin_address", bitcoinAddress)
add("withdrawal_mode", serializerFormat.encodeToJsonElement(mode))
idempotencyKey?.let { add("idempotency_key", idempotencyKey) }
},
signingNodeId = nodeId,
) {
Expand All @@ -805,15 +818,19 @@ class LightsparkCoroutinesClient private constructor(
* As guidance, a maximum fee of 15 basis points should make almost all transactions succeed. For example,
* for a transaction between 10k sats and 100k sats, this would mean a fee limit of 15 to 150 sats.
* @param timeoutSecs The timeout in seconds that we will try to make the payment.
* @param idempotencyKey An optional key to ensure idempotency of the payment. If provided, the same result will be
* returned for the same idempotency key without triggering a new payment.
* @return An `OutgoingPayment` object if the payment was successful, or throws if the payment failed.
* @throws LightsparkException if the payment failed.
*/
@JvmOverloads
suspend fun sendPayment(
payerNodeId: String,
destinationPublicKey: String,
amountMsats: Long,
maxFeesMsats: Long,
timeoutSecs: Int = 60,
idempotencyKey: String? = null,
): OutgoingPayment {
requireValidAuth()
return executeQuery(
Expand All @@ -825,6 +842,7 @@ class LightsparkCoroutinesClient private constructor(
add("amount_msats", amountMsats)
add("timeout_secs", timeoutSecs)
add("maximum_fees_msats", maxFeesMsats)
idempotencyKey?.let { add("idempotency_key", idempotencyKey) }
},
signingNodeId = payerNodeId,
) {
Expand Down
Loading