frost/bdk-ffi
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add required files for API docs 0.5.1

Browse Source
This commit is contained in:
thunderbiscuit 2022-03-19 11:01:18 -04:00
parent 6332e78375
commit aa13e113fa
No known key found for this signature in database
GPG Key ID: 88253696EB836462
4 changed files with 806 additions and 2090 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
android/Module.md
View File

@ -1,4 +1,4 @@
# Module bdk-android
The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for Android. Current version: `0.4.0`.
The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for Android. Current version: `0.5.1`.
# Package org.bitcoindevkit

2088
docs-0.4.0.patch
View File

File diff suppressed because it is too large Load Diff

804
docs.patch Normal file
View File

@ -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<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)

2
jvm/Module.md
View File

@ -1,4 +1,4 @@
# Module bdk-jvm
The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for the JVM. Current version: `0.4.0`.
The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for the JVM. Current version: `0.5.1`.
# Package org.bitcoindevkit