*** 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<InternalException> {
      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 <U> 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<Disposable>()
                  .forEach(Disposable::destroy)
          }
      }
  }
  
+ /**
+  * @suppress
+  */
  inline fun <T : Disposable?, R> 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<T>` 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<T>` 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<CallbackInterface>(
      protected val foreignCallback: ForeignCallback
  ) {
      val handleMap = ConcurrentHandleMap<CallbackInterface>()
  
      // 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)