From 07aa1f89505c2684412b6e6878a962c24c6d8669 Mon Sep 17 00:00:00 2001 From: thunderbiscuit Date: Wed, 1 Feb 2023 09:14:48 -0500 Subject: [PATCH] Add new AddressIndex variants to Kotlin API docs --- .../src/main/kotlin/org/bitcoindevkit/bdk.kt | 30 +++++++++++++++---- .../test/kotlin/org/bitcoindevkit/Samples.kt | 8 +++-- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/api-docs/kotlin/src/main/kotlin/org/bitcoindevkit/bdk.kt b/api-docs/kotlin/src/main/kotlin/org/bitcoindevkit/bdk.kt index bcfc21a..87b13b7 100644 --- a/api-docs/kotlin/src/main/kotlin/org/bitcoindevkit/bdk.kt +++ b/api-docs/kotlin/src/main/kotlin/org/bitcoindevkit/bdk.kt @@ -35,21 +35,41 @@ data class AddressInfo ( /** * The address index selection strategy to use to derive an address from the wallet’s external descriptor. * - * If you’re unsure which one to use, use `AddressIndex.NEW`. + * If you’re unsure which one to use, use `AddressIndex.New`. * * @sample org.bitcoindevkit.addressIndexSample */ -enum class AddressIndex { +sealed class AddressIndex { /** Return a new address after incrementing the current descriptor index. */ - NEW, + object New: AddressIndex(), - /** Return the address for the current descriptor index if it has not been used in a received transaction. + /** + * Return the address for the current descriptor index if it has not been used in a received transaction. * Otherwise return a new address as with `AddressIndex.NEW`. Use with caution, if the wallet * has not yet detected an address has been used it could return an already used address. * This function is primarily meant for situations where the caller is untrusted; * for example when deriving donation addresses on-demand for a public web page. */ - LAST_UNUSED, + object LastUnused: AddressIndex(), + + /** + * Return the address for a specific descriptor index. Does not change the current descriptor + * index used by [AddressIndex.New] and [AddressIndex.LastUsed]. + * Use with caution, if an index is given that is less than the current descriptor index + * then the returned address may have already been used. + */ + data class Peek(val index: UInt): AddressIndex(), + + /** + * Return the address for a specific descriptor index and reset the current descriptor index + * used by [AddressIndex.New] and [AddressIndex.LastUsed] to this value. + * Use with caution, if an index is given that is less than the current descriptor index + * then the returned address and subsequent addresses returned by calls to [AddressIndex.New] + * and [AddressIndex.LastUsed] may have already been used. Also if the index is reset to a + * value earlier than the [Blockchain] stopGap (default is 20) then a + * larger stopGap should be used to monitor for all possibly used addresses. + */ + data class Reset(val index: UInt): AddressIndex() } /** diff --git a/api-docs/kotlin/src/test/kotlin/org/bitcoindevkit/Samples.kt b/api-docs/kotlin/src/test/kotlin/org/bitcoindevkit/Samples.kt index 92dd0d7..373be59 100644 --- a/api-docs/kotlin/src/test/kotlin/org/bitcoindevkit/Samples.kt +++ b/api-docs/kotlin/src/test/kotlin/org/bitcoindevkit/Samples.kt @@ -73,7 +73,11 @@ fun addressIndexSample() { ) fun getLastUnusedAddress(): AddressInfo { - return wallet.getAddress(AddressIndex.LAST_UNUSED) + return wallet.getAddress(AddressIndex.LastUnused) + } + + fun peekAddress100(): AddressInfo { + return wallet.getAddress(AddressIndex.Peek(100u)) } } @@ -86,7 +90,7 @@ fun addressInfoSample() { ) fun getLastUnusedAddress(): AddressInfo { - return wallet.getAddress(AddressIndex.NEW) + return wallet.getAddress(AddressIndex.New) } val newAddress: AddressInfo = getLastUnusedAddress()