1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
Received: from sog-mx-4.v43.ch3.sourceforge.com ([172.29.43.194]
helo=mx.sourceforge.net)
by sfs-ml-1.v29.ch3.sourceforge.com with esmtp (Exim 4.76)
(envelope-from <dario.teixeira@nleyten.com>) id 1YNiHS-0003Sz-5h
for bitcoin-development@lists.sourceforge.net;
Tue, 17 Feb 2015 13:33:38 +0000
X-ACL-Warn:
Received: from relay4-d.mail.gandi.net ([217.70.183.196])
by sog-mx-4.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256)
(Exim 4.76) id 1YNiHQ-0005pm-J9
for bitcoin-development@lists.sourceforge.net;
Tue, 17 Feb 2015 13:33:38 +0000
Received: from mfilter1-d.gandi.net (mfilter1-d.gandi.net [217.70.178.130])
by relay4-d.mail.gandi.net (Postfix) with ESMTP id 79CE21720BE
for <bitcoin-development@lists.sourceforge.net>;
Tue, 17 Feb 2015 14:33:30 +0100 (CET)
X-Virus-Scanned: Debian amavisd-new at mfilter1-d.gandi.net
Received: from relay4-d.mail.gandi.net ([217.70.183.196])
by mfilter1-d.gandi.net (mfilter1-d.gandi.net [10.0.15.180])
(amavisd-new, port 10024) with ESMTP id n3kId01sYbT4
for <bitcoin-development@lists.sourceforge.net>;
Tue, 17 Feb 2015 14:33:28 +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 relay4-d.mail.gandi.net (Postfix) with ESMTPA id D918A17209B
for <bitcoin-development@lists.sourceforge.net>;
Tue, 17 Feb 2015 14:33:28 +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:33:28 +0000
From: Dario Teixeira <dario.teixeira@nleyten.com>
To: bitcoin-development@lists.sourceforge.net
In-Reply-To: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com>
References: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com>
Message-ID: <cc1f451ed0bcad909d203ece06e1040a@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: 1YNiHQ-0005pm-J9
Subject: Re: [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:33:38 -0000
Hi again,
My excuses: the formatting of the message seems to have been eaten
by a Gremlin. Here's a second attempt:
=================================================================
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
|
