diff options
author | Dario Teixeira <dario.teixeira@nleyten.com> | 2015-02-17 13:00:49 +0000 |
---|---|---|
committer | bitcoindev <bitcoindev@gnusha.org> | 2015-02-17 13:19:12 +0000 |
commit | bef1ce13c6b31f120b921b8b8fda353760c71db3 (patch) | |
tree | 46ca141f640e3cc38f537a45a10d12ae4d420442 | |
parent | 4eda0a10c8d394049e3c9865ffe4a86d91f16776 (diff) | |
download | pi-bitcoindev-bef1ce13c6b31f120b921b8b8fda353760c71db3.tar.gz pi-bitcoindev-bef1ce13c6b31f120b921b8b8fda353760c71db3.zip |
[Bitcoin-development] More precise type information in API reference
-rw-r--r-- | 1e/3518f02c257ab5f8345367b923c5504e579867 | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/1e/3518f02c257ab5f8345367b923c5504e579867 b/1e/3518f02c257ab5f8345367b923c5504e579867 new file mode 100644 index 000000000..9aae2e4ca --- /dev/null +++ b/1e/3518f02c257ab5f8345367b923c5504e579867 @@ -0,0 +1,174 @@ +Received: from sog-mx-4.v43.ch3.sourceforge.com ([172.29.43.194] + helo=mx.sourceforge.net) + by sfs-ml-4.v29.ch3.sourceforge.com with esmtp (Exim 4.76) + (envelope-from <dario.teixeira@nleyten.com>) id 1YNi3U-0006f2-Dw + for bitcoin-development@lists.sourceforge.net; + Tue, 17 Feb 2015 13:19:12 +0000 +X-ACL-Warn: +Received: from slow1-d.mail.gandi.net ([217.70.178.86]) + by sog-mx-4.v43.ch3.sourceforge.com with esmtp (Exim 4.76) + id 1YNi3S-0005TY-PJ for bitcoin-development@lists.sourceforge.net; + Tue, 17 Feb 2015 13:19:12 +0000 +Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net + [217.70.183.197]) + by slow1-d.mail.gandi.net (Postfix) with ESMTP id C12624961EC + for <bitcoin-development@lists.sourceforge.net>; + Tue, 17 Feb 2015 14:00:59 +0100 (CET) +Received: from mfilter30-d.gandi.net (mfilter30-d.gandi.net [217.70.178.161]) + by relay5-d.mail.gandi.net (Postfix) with ESMTP id 263A841C0E7 + for <bitcoin-development@lists.sourceforge.net>; + Tue, 17 Feb 2015 14:00:51 +0100 (CET) +X-Virus-Scanned: Debian amavisd-new at mfilter30-d.gandi.net +Received: from relay5-d.mail.gandi.net ([217.70.183.197]) + by mfilter30-d.gandi.net (mfilter30-d.gandi.net [10.0.15.180]) + (amavisd-new, port 10024) with ESMTP id 14dGA5Xvj+-t + for <bitcoin-development@lists.sourceforge.net>; + Tue, 17 Feb 2015 14:00:49 +0100 (CET) +X-Originating-IP: 10.58.1.142 +Received: from webmail.gandi.net (unknown [10.58.1.142]) + (Authenticated sender: dario.teixeira@nleyten.com) + by relay5-d.mail.gandi.net (Postfix) with ESMTPA id A279C41C104 + for <bitcoin-development@lists.sourceforge.net>; + Tue, 17 Feb 2015 14:00:49 +0100 (CET) +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8; + format=flowed +Content-Transfer-Encoding: 7bit +Date: Tue, 17 Feb 2015 13:00:49 +0000 +From: Dario Teixeira <dario.teixeira@nleyten.com> +To: bitcoin-development@lists.sourceforge.net +Message-ID: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com> +X-Sender: dario.teixeira@nleyten.com +User-Agent: Roundcube Webmail/0.9.5 +X-Spam-Score: 0.0 (/) +X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. + See http://spamassassin.org/tag/ for more details. +X-Headers-End: 1YNi3S-0005TY-PJ +Subject: [Bitcoin-development] More precise type information in API reference +X-BeenThere: bitcoin-development@lists.sourceforge.net +X-Mailman-Version: 2.1.9 +Precedence: list +List-Id: <bitcoin-development.lists.sourceforge.net> +List-Unsubscribe: <https://lists.sourceforge.net/lists/listinfo/bitcoin-development>, + <mailto:bitcoin-development-request@lists.sourceforge.net?subject=unsubscribe> +List-Archive: <http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development> +List-Post: <mailto:bitcoin-development@lists.sourceforge.net> +List-Help: <mailto:bitcoin-development-request@lists.sourceforge.net?subject=help> +List-Subscribe: <https://lists.sourceforge.net/lists/listinfo/bitcoin-development>, + <mailto:bitcoin-development-request@lists.sourceforge.net?subject=subscribe> +X-List-Received-Date: Tue, 17 Feb 2015 13:19:12 -0000 + +Dear Bitcoin devs, + +I am the author of OCaml-bitcoin [1], a library offering an OCaml +interface +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 +and +expressive type system [2]. Given its emphasis on safety, its +industrial +users are disproportionally found in the aerospace and financial +sectors. + +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 +type +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 +at +the API offered by OCaml-bitcoin [4], and the associated type +definitions +[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 +Bitcoin +wiki and from looking at the Bitcoin Core source-code. I wouldn't be +surprised +if it contains errors, because neither the source-code nor the wiki is +very +precise about the actual types being used. As an example, consider type +hexspk_t ("hex representation of script public key"). Is this really +the +same type used in both signrawtransaction and createmultisig? + +Improving this situation would pose a minimal burden on bitcoin devs: +all +that would be required is defining the precise set of types used in the +RPC +API, and annotating the RPC calls either in the source-code itself or in +the +API reference documentation. It would make writing bindings such as +mine +far easier and less error prone, and it would have the added advantage +of +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 +JSON +object without any attempt to process it. This is because that's a +fairly +niche facility, and the bindings would balloon in size if I were to +process +every single large return object. Instead, the bindings take the more +pragmatic stance of only processing the parameters and return results +where +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 +bindings + know that even if a public ECDSA key is serialised as a string, it +does + not stop being a public ECDSA key, and should only be used where a +public + ECDSA key is expected. + + Q: What does it matter if the types are not even distinguished in the +C++ + source of Bitcoin Core? + + A: That is unfortunate, because it opens the door to bugs caused by +type + errors. Moreover, even if the C++ source is "stringly-typed" and +does + not enforce a strong type discipline, that does not mean that the +types + are not there. Even if a public and private key are both +represented + as strings, can you use one where the other is expected? If not, +then + they actually have different types! + + Q: Isn't this a maintenance nightmare, given the changes to Bitcoin +core? + + 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 +put +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 + + + |