diff --git a/android/Module.md b/android/Module.md new file mode 100644 index 0000000..d21953b --- /dev/null +++ b/android/Module.md @@ -0,0 +1,4 @@ +# Module bdk-android +The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for Android. + +# Package org.bitcoindevkit diff --git a/android/build.gradle.kts b/android/build.gradle.kts index eb87810..df2a47f 100644 --- a/android/build.gradle.kts +++ b/android/build.gradle.kts @@ -3,6 +3,7 @@ plugins { id("kotlin-android") id("maven-publish") id("signing") + id("org.jetbrains.dokka") version "1.6.10" } android { @@ -94,3 +95,12 @@ signing { useGpgCmd() sign(publishing.publications) } + +tasks.withType().configureEach { + dokkaSourceSets { + named("main") { + moduleName.set("bdk-android") + includes.from("Module.md") + } + } +} \ No newline at end of file diff --git a/docs.patch b/docs.patch new file mode 100644 index 0000000..21cb4e9 --- /dev/null +++ b/docs.patch @@ -0,0 +1,804 @@ +*** bdk-0.5.1-undocumented.kt 2022-03-19 10:29:15.000000000 -0400 +--- bdk-0.5.1-documented.kt 2022-03-19 10:27:57.000000000 -0400 +*************** +*** 17,131 **** +--- 17,144 ---- + // compile the Rust component. The easiest way to ensure this is to bundle the Kotlin + // helpers directly inline like we're doing here. + + import com.sun.jna.Library + import com.sun.jna.Native + import com.sun.jna.Pointer + import com.sun.jna.Structure + import com.sun.jna.ptr.ByReference + import java.nio.ByteBuffer + import java.nio.ByteOrder + import java.util.concurrent.atomic.AtomicBoolean + import java.util.concurrent.atomic.AtomicLong + import java.util.concurrent.locks.ReentrantLock + import kotlin.concurrent.withLock + + // The Rust Buffer and 3 templated methods (alloc, free, reserve). + // This is a helper for safely working with byte buffers returned from the Rust code. + // A rust-owned buffer is represented by its capacity, its current length, and a + // pointer to the underlying data. + ++ ++ /** ++ * @suppress ++ */ + @Structure.FieldOrder("capacity", "len", "data") + open class RustBuffer : Structure() { + @JvmField var capacity: Int = 0 + @JvmField var len: Int = 0 + @JvmField var data: Pointer? = null + + class ByValue : RustBuffer(), Structure.ByValue + class ByReference : RustBuffer(), Structure.ByReference + + companion object { + internal fun alloc(size: Int = 0) = rustCall() { status -> + _UniFFILib.INSTANCE.ffi_bdk_2b7a_rustbuffer_alloc(size, status).also { + if(it.data == null) { + throw RuntimeException("RustBuffer.alloc() returned null data pointer (size=${size})") + } + } + } + + internal fun free(buf: RustBuffer.ByValue) = rustCall() { status -> + _UniFFILib.INSTANCE.ffi_bdk_2b7a_rustbuffer_free(buf, status) + } + + internal fun reserve(buf: RustBuffer.ByValue, additional: Int) = rustCall() { status -> + _UniFFILib.INSTANCE.ffi_bdk_2b7a_rustbuffer_reserve(buf, additional, status) + } + } + + @Suppress("TooGenericExceptionThrown") + fun asByteBuffer() = + this.data?.getByteBuffer(0, this.len.toLong())?.also { + it.order(ByteOrder.BIG_ENDIAN) + } + } + + /** + * The equivalent of the `*mut RustBuffer` type. + * Required for callbacks taking in an out pointer. + * + * Size is the sum of all values in the struct. + */ ++ /** ++ * @suppress ++ */ + class RustBufferByReference : ByReference(16) { + /** + * Set the pointed-to `RustBuffer` to the given value. + */ + fun setValue(value: RustBuffer.ByValue) { + // NOTE: The offsets are as they are in the C-like struct. + val pointer = getPointer() + pointer.setInt(0, value.capacity) + pointer.setInt(4, value.len) + pointer.setPointer(8, value.data) + } + } + + // This is a helper for safely passing byte references into the rust code. + // It's not actually used at the moment, because there aren't many things that you + // can take a direct pointer to in the JVM, and if we're going to copy something + // then we might as well copy it into a `RustBuffer`. But it's here for API + // completeness. + ++ /** ++ * @suppress ++ */ + @Structure.FieldOrder("len", "data") + open class ForeignBytes : Structure() { + @JvmField var len: Int = 0 + @JvmField var data: Pointer? = null + + class ByValue : ForeignBytes(), Structure.ByValue + } + + + // A helper for structured writing of data into a `RustBuffer`. + // This is very similar to `java.nio.ByteBuffer` but it knows how to grow + // the underlying `RustBuffer` on demand. + // + // TODO: we should benchmark writing things into a `RustBuffer` versus building + // up a bytearray and then copying it across. + ++ /** ++ * @suppress ++ */ + class RustBufferBuilder() { + var rbuf = RustBuffer.ByValue() + var bbuf: ByteBuffer? = null + + init { + val rbuf = RustBuffer.alloc(16) // Totally arbitrary initial size + rbuf.writeField("len", 0) + this.setRustBuffer(rbuf) + } + + internal fun setRustBuffer(rbuf: RustBuffer.ByValue) { + this.rbuf = rbuf + this.bbuf = this.rbuf.data?.getByteBuffer(0, this.rbuf.capacity.toLong())?.also { + it.order(ByteOrder.BIG_ENDIAN) + it.position(rbuf.len) + } + } + + fun finalize() : RustBuffer.ByValue { + val rbuf = this.rbuf +*************** +*** 266,305 **** +--- 279,321 ---- + val return_value = callback(status) + if (status.isSuccess()) { + return return_value + } else if (status.isError()) { + throw errorHandler.lift(status.error_buf) + } else if (status.isPanic()) { + // when the rust code sees a panic, it tries to construct a rustbuffer + // with the message. but if that code panics, then it just sends back + // an empty buffer. + if (status.error_buf.len > 0) { + throw InternalException(String.lift(status.error_buf)) + } else { + throw InternalException("Rust panic") + } + } else { + throw InternalException("Unknown rust call status: $status.code") + } + } + + // CallStatusErrorHandler implementation for times when we don't expect a CALL_ERROR ++ /** ++ * @suppress ++ */ + object NullCallStatusErrorHandler: CallStatusErrorHandler { + override fun lift(error_buf: RustBuffer.ByValue): InternalException { + RustBuffer.free(error_buf) + return InternalException("Unexpected CALL_ERROR") + } + } + + // Call a rust function that returns a plain value + private inline fun rustCall(callback: (RustCallStatus) -> U): U { + return rustCallWithError(NullCallStatusErrorHandler, callback); + } + + // Contains loading, initialization code, + // and the FFI Function declarations in a com.sun.jna.Library. + @Synchronized + private fun findLibraryName(componentName: String): String { + val libOverride = System.getProperty("uniffi.component.$componentName.libraryOverride") + if (libOverride != null) { + return libOverride + } +*************** +*** 406,455 **** +--- 422,477 ---- + uniffi_out_err: RustCallStatus + ): Unit + + fun ffi_bdk_2b7a_rustbuffer_reserve(buf: RustBuffer.ByValue,additional: Int, + uniffi_out_err: RustCallStatus + ): RustBuffer.ByValue + + + } + + // Public interface members begin here. + + // Interface implemented by anything that can contain an object reference. + // + // Such types expose a `destroy()` method that must be called to cleanly + // dispose of the contained objects. Failure to call this method may result + // in memory leaks. + // + // The easiest way to ensure this method is called is to use the `.use` + // helper method to execute a block and destroy the object at the end. ++ /** ++ * @suppress ++ */ + interface Disposable { + fun destroy() + companion object { + fun destroy(vararg args: Any?) { + args.filterIsInstance() + .forEach(Disposable::destroy) + } + } + } + ++ /** ++ * @suppress ++ */ + inline fun T.use(block: (T) -> R) = + try { + block(this) + } finally { + try { + // N.B. our implementation is on the nullable type `Disposable?`. + this?.destroy() + } catch (e: Throwable) { + // swallow + } + } + + // The base class for all UniFFI Object types. + // + // This class provides core operations for working with the Rust `Arc` pointer to + // the live Rust struct on the other side of the FFI. + // + // There's some subtlety here, because we have to be careful not to operate on a Rust + // struct after it has been dropped, and because we must expose a public API for freeing + // the Kotlin wrapper object in lieu of reliable finalizers. The core requirements are: +*************** +*** 509,548 **** +--- 531,573 ---- + // Otherwise we atomically decrement and check the counter. + // If it has reached zero then we destroy the underlying Rust struct. + // + // Astute readers may observe that this all sounds very similar to the way that Rust's `Arc` works, + // and indeed it is, with the addition of a flag to guard against multiple calls to `destroy`. + // + // The overall effect is that the underlying Rust struct is destroyed only when `destroy` has been + // called *and* all in-flight method calls have completed, avoiding violating any of the expectations + // of the underlying Rust code. + // + // In the future we may be able to replace some of this with automatic finalization logic, such as using + // the new "Cleaner" functionaility in Java 9. The above scheme has been designed to work even if `destroy` is + // invoked by garbage-collection machinery rather than by calling code (which by the way, it's apparently also + // possible for the JVM to finalize an object while there is an in-flight call to one of its methods [1], + // so there would still be some complexity here). + // + // Sigh...all of this for want of a robust finalization mechanism. + // + // [1] https://stackoverflow.com/questions/24376768/can-java-finalize-an-object-when-it-is-still-in-scope/24380219 + // ++ /** ++ * @suppress ++ */ + abstract class FFIObject( + protected val pointer: Pointer + ): Disposable, AutoCloseable { + + private val wasDestroyed = AtomicBoolean(false) + private val callCounter = AtomicLong(1) + + open protected fun freeRustArcPtr() { + // To be overridden in subclasses. + } + + override fun destroy() { + // Only allow a single call to this method. + // TODO: maybe we should log a warning if called more than once? + if (this.wasDestroyed.compareAndSet(false, true)) { + // This decrement always matches the initial count of 1 given at creation time. + if (this.callCounter.decrementAndGet() == 0L) { + this.freeRustArcPtr() + } + } +*************** +*** 595,712 **** +--- 620,746 ---- + } + } + + fun get(handle: Handle) = lock.withLock { + leftMap[handle] + } + + fun delete(handle: Handle) { + this.remove(handle) + } + + fun remove(handle: Handle): T? = + lock.withLock { + leftMap.remove(handle)?.let { obj -> + rightMap.remove(obj) + obj + } + } + } + ++ /** ++ * @suppress ++ */ + interface ForeignCallback : com.sun.jna.Callback { + public fun invoke(handle: Handle, method: Int, args: RustBuffer.ByValue, outBuf: RustBufferByReference): Int + } + + // Magic number for the Rust proxy to call using the same mechanism as every other method, + // to free the callback once it's dropped by Rust. + internal const val IDX_CALLBACK_FREE = 0 + + internal abstract class FfiConverterCallbackInterface( + protected val foreignCallback: ForeignCallback + ) { + val handleMap = ConcurrentHandleMap() + + // Registers the foreign callback with the Rust side. + // This method is generated for each callback interface. + abstract fun register(lib: _UniFFILib) + + fun drop(handle: Handle): RustBuffer.ByValue { + return handleMap.remove(handle).let { RustBuffer.ByValue() } + } + + fun lift(n: Handle) = handleMap.get(n) + + fun read(buf: ByteBuffer) = lift(buf.getLong()) + + fun lower(v: CallbackInterface) = + handleMap.insert(v).also { + assert(handleMap.get(it) === v) { "Handle map is not returning the object we just placed there. This is a bug in the HandleMap." } + } + + fun write(v: CallbackInterface, buf: RustBufferBuilder) = + buf.putLong(lower(v)) + } + + + + enum class Network { + BITCOIN,TESTNET,SIGNET,REGTEST; + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): Network { + return liftFromRustBuffer(rbuf) { buf -> Network.read(buf) } + } + + internal fun read(buf: ByteBuffer) = + try { values()[buf.getInt() - 1] } + catch (e: IndexOutOfBoundsException) { + throw RuntimeException("invalid enum value, something is very wrong!!", e) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + + internal fun write(buf: RustBufferBuilder) { + buf.putInt(this.ordinal + 1) + } + } + + + + + + + + sealed class DatabaseConfig { + object Memory : DatabaseConfig() + + data class Sled( + val config: SledDbConfiguration + ) : DatabaseConfig() + + data class Sqlite( + val config: SqliteDbConfiguration + ) : DatabaseConfig() + + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): DatabaseConfig { + return liftFromRustBuffer(rbuf) { buf -> DatabaseConfig.read(buf) } + } + + internal fun read(buf: ByteBuffer): DatabaseConfig { + return when(buf.getInt()) { + 1 -> DatabaseConfig.Memory + 2 -> DatabaseConfig.Sled( + SledDbConfiguration.read(buf) + ) + 3 -> DatabaseConfig.Sqlite( + SqliteDbConfiguration.read(buf) + ) + else -> throw RuntimeException("invalid enum value, something is very wrong!!") + } + } + } + + internal fun lower(): RustBuffer.ByValue { +*************** +*** 737,776 **** +--- 771,813 ---- + } + + + + + + + + sealed class Transaction { + + data class Unconfirmed( + val details: TransactionDetails + ) : Transaction() + + data class Confirmed( + val details: TransactionDetails, + val confirmation: BlockTime + ) : Transaction() + + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): Transaction { + return liftFromRustBuffer(rbuf) { buf -> Transaction.read(buf) } + } + + internal fun read(buf: ByteBuffer): Transaction { + return when(buf.getInt()) { + 1 -> Transaction.Unconfirmed( + TransactionDetails.read(buf) + ) + 2 -> Transaction.Confirmed( + TransactionDetails.read(buf), + BlockTime.read(buf) + ) + else -> throw RuntimeException("invalid enum value, something is very wrong!!") + } + } + } + + internal fun lower(): RustBuffer.ByValue { +*************** +*** 786,836 **** +--- 823,879 ---- + } + is Transaction.Confirmed -> { + buf.putInt(2) + this.details.write(buf) + this.confirmation.write(buf) + + } + }.let { /* this makes the `when` an expression, which ensures it is exhaustive */ } + } + + + + } + + + + + + + ++ /** ++ * Sealed class that can be of either blockchain configuration defined by the library. ++ */ + sealed class BlockchainConfig { + + data class Electrum( + val config: ElectrumConfig + ) : BlockchainConfig() + + data class Esplora( + val config: EsploraConfig + ) : BlockchainConfig() + + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): BlockchainConfig { + return liftFromRustBuffer(rbuf) { buf -> BlockchainConfig.read(buf) } + } + + internal fun read(buf: ByteBuffer): BlockchainConfig { + return when(buf.getInt()) { + 1 -> BlockchainConfig.Electrum( + ElectrumConfig.read(buf) + ) + 2 -> BlockchainConfig.Esplora( + EsploraConfig.read(buf) + ) + else -> throw RuntimeException("invalid enum value, something is very wrong!!") + } + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) +*************** +*** 845,884 **** +--- 888,930 ---- + } + is BlockchainConfig.Esplora -> { + buf.putInt(2) + this.config.write(buf) + + } + }.let { /* this makes the `when` an expression, which ensures it is exhaustive */ } + } + + + + } + + + + + + enum class WordCount { + WORDS12,WORDS15,WORDS18,WORDS21,WORDS24; + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): WordCount { + return liftFromRustBuffer(rbuf) { buf -> WordCount.read(buf) } + } + + internal fun read(buf: ByteBuffer) = + try { values()[buf.getInt() - 1] } + catch (e: IndexOutOfBoundsException) { + throw RuntimeException("invalid enum value, something is very wrong!!", e) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + + internal fun write(buf: RustBufferBuilder) { + buf.putInt(this.ordinal + 1) + } + } +*************** +*** 1084,1123 **** +--- 1130,1172 ---- + + internal fun lower(): Pointer = callWithPointer { it } + + internal fun write(buf: RustBufferBuilder) { + // The Rust code always expects pointers written as 8 bytes, + // and will fail to compile if they don't fit. + buf.putLong(Pointer.nativeValue(this.lower())) + } + + override fun serialize(): String = + callWithPointer { + rustCall() { status -> + _UniFFILib.INSTANCE.bdk_2b7a_PartiallySignedBitcoinTransaction_serialize(it, status) + } + }.let { + String.lift(it) + } + + + ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(ptr: Pointer): PartiallySignedBitcoinTransaction { + return PartiallySignedBitcoinTransaction(ptr) + } + + internal fun read(buf: ByteBuffer): PartiallySignedBitcoinTransaction { + // The Rust code always writes pointers as 8 bytes, and will + // fail to compile if they don't fit. + return PartiallySignedBitcoinTransaction.lift(Pointer(buf.getLong())) + } + + fun deserialize(psbtBase64: String ): PartiallySignedBitcoinTransaction = + PartiallySignedBitcoinTransaction( + rustCallWithError(BdkException) { status -> + _UniFFILib.INSTANCE.bdk_2b7a_PartiallySignedBitcoinTransaction_deserialize(psbtBase64.lower() ,status) + }) + + } + } + +*************** +*** 1204,1282 **** +--- 1253,1349 ---- + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + + internal fun write(buf: RustBufferBuilder) { + writeOptionalULong(this.fees, buf) + + this.received.write(buf) + + this.sent.write(buf) + + this.txid.write(buf) + + } + + + + } + ++ /** ++ * Block height and timestamp of a block ++ */ + data class BlockTime ( + var height: UInt, + var timestamp: ULong + ) { ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): BlockTime { + return liftFromRustBuffer(rbuf) { buf -> BlockTime.read(buf) } + } + + internal fun read(buf: ByteBuffer): BlockTime { + return BlockTime( + UInt.read(buf), + ULong.read(buf) + ) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + + internal fun write(buf: RustBufferBuilder) { + this.height.write(buf) + + this.timestamp.write(buf) + + } + + + + } + ++ /** ++ * Configuration for an ElectrumBlockchain ++ * ++ * @property url URL of the Electrum server (such as ElectrumX, Esplora, BWT). May start with `ssl://` or `tcp://` and include a port, `e.g. ssl://electrum.blockstream.info:60002` ++ * @property socks5 URL of the socks5 proxy server or a Tor service ++ * @property retry Request retry count ++ * @property timeout Request timeout in seconds ++ * @property stopGap Stop searching addresses for transactions after finding an unused gap of this length ++ */ + data class ElectrumConfig ( + var url: String, + var socks5: String?, + var retry: UByte, + var timeout: UByte?, + var stopGap: ULong + ) { ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): ElectrumConfig { + return liftFromRustBuffer(rbuf) { buf -> ElectrumConfig.read(buf) } + } + + internal fun read(buf: ByteBuffer): ElectrumConfig { + return ElectrumConfig( + String.read(buf), + readOptionalString(buf), + UByte.read(buf), + readOptionalUByte(buf), + ULong.read(buf) + ) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + +*************** +*** 1287,1326 **** +--- 1354,1396 ---- + + this.retry.write(buf) + + writeOptionalUByte(this.timeout, buf) + + this.stopGap.write(buf) + + } + + + + } + + data class EsploraConfig ( + var baseUrl: String, + var proxy: String?, + var timeoutRead: ULong, + var timeoutWrite: ULong, + var stopGap: ULong + ) { ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): EsploraConfig { + return liftFromRustBuffer(rbuf) { buf -> EsploraConfig.read(buf) } + } + + internal fun read(buf: ByteBuffer): EsploraConfig { + return EsploraConfig( + String.read(buf), + readOptionalString(buf), + ULong.read(buf), + ULong.read(buf), + ULong.read(buf) + ) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + +*************** +*** 1329,1368 **** +--- 1399,1441 ---- + + writeOptionalString(this.proxy, buf) + + this.timeoutRead.write(buf) + + this.timeoutWrite.write(buf) + + this.stopGap.write(buf) + + } + + + + } + + data class ExtendedKeyInfo ( + var mnemonic: String, + var xprv: String, + var fingerprint: String + ) { ++ /** ++ * @suppress ++ */ + companion object { + internal fun lift(rbuf: RustBuffer.ByValue): ExtendedKeyInfo { + return liftFromRustBuffer(rbuf) { buf -> ExtendedKeyInfo.read(buf) } + } + + internal fun read(buf: ByteBuffer): ExtendedKeyInfo { + return ExtendedKeyInfo( + String.read(buf), + String.read(buf), + String.read(buf) + ) + } + } + + internal fun lower(): RustBuffer.ByValue { + return lowerIntoRustBuffer(this, {v, buf -> v.write(buf)}) + } + + internal fun write(buf: RustBufferBuilder) { + this.mnemonic.write(buf) diff --git a/jvm/Module.md b/jvm/Module.md new file mode 100644 index 0000000..6873108 --- /dev/null +++ b/jvm/Module.md @@ -0,0 +1,4 @@ +# Module bdk-jvm +The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for the JVM. + +# Package org.bitcoindevkit diff --git a/jvm/build.gradle.kts b/jvm/build.gradle.kts index dcf9426..a087fca 100644 --- a/jvm/build.gradle.kts +++ b/jvm/build.gradle.kts @@ -6,6 +6,7 @@ plugins { id("java-library") id("maven-publish") id("signing") + id("org.jetbrains.dokka") version "1.6.10" } java { @@ -90,3 +91,12 @@ signing { useGpgCmd() sign(publishing.publications) } + +tasks.withType().configureEach { + dokkaSourceSets { + named("main") { + moduleName.set("bdk-jvm") + includes.from("Module.md") + } + } +}