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

docs: add information and examples to adr readme

Browse Source
This commit is contained in:
thunderbiscuit 2023-12-07 13:19:42 -05:00
parent 53b59d5100
commit c9019e9fcf
No known key found for this signature in database
GPG Key ID: 88253696EB836462
3 changed files with 21 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/adr/01-naming.md
View File

@ -1,17 +1,21 @@
# Naming convention
Producing language bindings potentially requires renaming a number of types and methods, and this document outlines the approach we have decided to take when thinking through this problem for bdk-ffi libraries.
## Context and Problem Statement
The tool we use to produce language bindings for bdk-ffi libraries is [uniffi]. While the library is powerful, it also comes with some caveats. Some of those include the inability to expose to foreign bindings Rust-specific types like tuples, and the inability to expose generics. This means that at least _some_ wrapping and transforming of certain things are required between the pure Rust code coming from the bdk library and the final language bindings in Swift, Kotlin, and Python.
With wrapping comes (a) the requirement for naming potentially new types, and (b) the ability to "wrap" behaviour that could be useful for end users. This document addresses point (a).
## Decision Drivers
Our main goals are:
1. Keep the multiple language bindings libraries maintainable.
2. Help user of bdk help each other and working with a similarly shaped API across languages.
2. Help users of bdk help each other and working with a similarly shaped API across languages.
## Decision Outcome
We decided to try and keep the names of all types the same between the Rust libraries and the bindings, and in cases where new types had to be created, to keep them in the style and spirit of the bdk and rust-bitcoin libraries.
There is so far one exception to this rule, where we renamed the `ScriptBuf` type from rust-bitcoin to `Script`. This was done because the concept of owned vs. borrowed types is strictly a Rust concept, and is not passed onto the languages bindings in any way, and therefore keeping the script type as `Script` was our preferred option in this case.

6
docs/adr/02-wrapping.md
View File

@ -1,17 +1,21 @@
# Wrapping BDK APIs
Producing language bindings potentially requires wrapping a number of APIs, and this document outlines the approach we have decided to take when thinking through this problem for bdk-ffi libraries.
## Context and Problem Statement
The tool we use to produce language bindings for bdk-ffi libraries is [uniffi]. While the library is powerful, it also comes with some caveats. Some of those include the inability to expose to foreign bindings Rust-specific types like tuples, and the inability to expose generics. This means that at least _some_ wrapping and transforming of certain things are required between the pure Rust code coming from the bdk library and the final language bindings in Swift, Kotlin, and Python.
With wrapping comes (a) the requirement for naming potentially new types, and (b) the ability to "wrap" behaviour that could be useful for end users. This document addresses point (b).
## Decision Drivers
Our main goals are:
1. Keep the multiple language bindings libraries maintainable.
2. Help user of bdk help each other and working with a similarly shaped API across languages.
2. Help users of bdk help each other and working with a similarly shaped API across languages.
## Decision Outcome
There are three potential reasons for wrapping Rust BDK APIs:
1. The Rust types are not available in the target language (e.g., a function returns a tuple, which can't be returned in Swift/Kotlin)
2. Some complex functionality is available in the Rust bitcoin/miniscript/bdk ecosystem, but exposing all underlying types required for this functionality is out of scope at the time a particular feature is required

12
docs/adr/README.md
View File

@ -1,2 +1,12 @@
# Architectural Decision Records
This directory contains a series of Architectural Decision Records or "ADRs" for the uniffi project. We're going to try to use it as a kind of collective memory of the decisions we've made and the path we've taken to get the project to its current point.
This directory contains a series of Architectural Decision Records or "ADRs" for the bdk-ffi project. We're going to use it as a kind of collective memory of the decisions we've made and the path we've taken to get the project to its current point.
A good example of simple and well executed ADRs can be found on the [uniffi](https://github.com/mozilla/uniffi-rs/) project repository. See their [readme](https://github.com/mozilla/uniffi-rs/tree/main/docs/adr) and [template](https://github.com/mozilla/uniffi-rs/blob/main/docs/adr/template.md) for more information.
Some more readings on ADRs:
- https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://adr.github.io/
- https://betterprogramming.pub/the-ultimate-guide-to-architectural-decision-records-6d74fd3850ee
- https://www.redhat.com/architect/architecture-decision-records