[Bitcoin-development] More precise type information in API reference

Dario Teixeira dario.teixeira at nleyten.com
Tue Feb 17 13:00:49 UTC 2015

Dear Bitcoin devs,

I am the author of OCaml-bitcoin [1], a library offering an OCaml 
to the official Bitcoin client API.  For those who may be unfamiliar 
with it,
OCaml is one of those functional programming languages with a very rich 
expressive type system [2].  Given its emphasis on safety, its 
users are disproportionally found in the aerospace and financial 

Now, OCaml programmers care a lot about types, because experience has
taught them that deep down most programming errors are just type errors.
 From this stems my request: please consider defining more precisely the 
information associated with each API call in the JSON-RPC reference [3].

To give you a better idea of what I'm talking about, please take a look 
the API offered by OCaml-bitcoin [4], and the associated type 
[5] (note that these have not been updated for Bitcoin Core 0.10 yet).
I've created the type definitions from information gathered from the 
wiki and from looking at the Bitcoin Core source-code.  I wouldn't be 
if it contains errors, because neither the source-code nor the wiki is 
precise about the actual types being used.  As an example, consider type
hexspk_t ("hex representation of script public key").  Is this really 
same type used in both signrawtransaction and createmultisig?

Improving this situation would pose a minimal burden on bitcoin devs: 
that would be required is defining the precise set of types used in the 
API, and annotating the RPC calls either in the source-code itself or in 
API reference documentation.  It would make writing bindings such as 
far easier and less error prone, and it would have the added advantage 
better documenting the Bitcoin Core source-code itself.

Also, note that it is not necessary to extend this request to the deep
data structures returned by some API calls.  Consider for instance the
gettransaction function of the OCaml-bitcoin API: it returns the raw 
object without any attempt to process it.  This is because that's a 
niche facility, and the bindings would balloon in size if I were to 
every single large return object.  Instead, the bindings take the more
pragmatic stance of only processing the parameters and return results 
a strong type discipline is imperative.

When I raised this issue on IRC a number of questions were posed.
What follows is my attempt to answer them:

   Q: What does it matter, if JSON only has a tiny set of types?

   A: JSON being the serialisation format is irrelevant.  The client 
      know that even if a public ECDSA key is serialised as a string, it 
      not stop being a public ECDSA key, and should only be used where a 
      ECDSA key is expected.

   Q: What does it matter if the types are not even distinguished in the 
      source of Bitcoin Core?

   A: That is unfortunate, because it opens the door to bugs caused by 
      errors.  Moreover, even if the C++ source is "stringly-typed" and 
      not enforce a strong type discipline, that does not mean that the 
      are not there.  Even if a public and private key are both 
      as strings, can you use one where the other is expected?  If not, 
      they actually have different types!

   Q: Isn't this a maintenance nightmare, given the changes to Bitcoin 

   A: Actually, the most burdensome part is what motivated this message:
      keeping track of the types used.  If the Bitcoin API reference were
      more precise, keeping the bindings up-to-date would be trivial and
      even mechanical, because the API is now fairly stable.

Thank you very much for your attention, and for all the work you guys 
into Bitcoin development.  It is much appreciated and not acknowledged
often enough!

Best regards,
Dario Teixeira

[1] https://github.com/darioteixeira/ocaml-bitcoin
[2] http://ocaml.org/learn/description.html
[3] https://bitcoin.org/en/developer-reference#bitcoin-core-apis
[4] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.ENGINE.html
[5] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.html

More information about the bitcoin-dev mailing list