summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDario Teixeira <dario.teixeira@nleyten.com>2015-02-17 13:00:49 +0000
committerbitcoindev <bitcoindev@gnusha.org>2015-02-17 13:19:12 +0000
commitbef1ce13c6b31f120b921b8b8fda353760c71db3 (patch)
tree46ca141f640e3cc38f537a45a10d12ae4d420442
parent4eda0a10c8d394049e3c9865ffe4a86d91f16776 (diff)
downloadpi-bitcoindev-bef1ce13c6b31f120b921b8b8fda353760c71db3.tar.gz
pi-bitcoindev-bef1ce13c6b31f120b921b8b8fda353760c71db3.zip
[Bitcoin-development] More precise type information in API reference
-rw-r--r--1e/3518f02c257ab5f8345367b923c5504e579867174
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
+
+
+