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
|
Received: from sog-mx-3.v43.ch3.sourceforge.com ([172.29.43.193]
helo=mx.sourceforge.net)
by sfs-ml-1.v29.ch3.sourceforge.com with esmtp (Exim 4.76)
(envelope-from <dario.teixeira@nleyten.com>) id 1YNnAQ-0003lx-1O
for bitcoin-development@lists.sourceforge.net;
Tue, 17 Feb 2015 18:46:42 +0000
X-ACL-Warn:
Received: from relay3-d.mail.gandi.net ([217.70.183.195])
by sog-mx-3.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256)
(Exim 4.76) id 1YNnAO-0000ZK-OO
for bitcoin-development@lists.sourceforge.net;
Tue, 17 Feb 2015 18:46:42 +0000
Received: from mfilter12-d.gandi.net (mfilter12-d.gandi.net [217.70.178.129])
by relay3-d.mail.gandi.net (Postfix) with ESMTP id 50ADAA80D0;
Tue, 17 Feb 2015 19:46:34 +0100 (CET)
X-Virus-Scanned: Debian amavisd-new at mfilter12-d.gandi.net
Received: from relay3-d.mail.gandi.net ([217.70.183.195])
by mfilter12-d.gandi.net (mfilter12-d.gandi.net [10.0.15.180])
(amavisd-new, port 10024)
with ESMTP id RZemUo-28tzY; Tue, 17 Feb 2015 19:46:17 +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 relay3-d.mail.gandi.net (Postfix) with ESMTPA id 6AEE4A80BC;
Tue, 17 Feb 2015 19:46:17 +0100 (CET)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
format=flowed
Content-Transfer-Encoding: 7bit
Date: Tue, 17 Feb 2015 18:46:17 +0000
From: Dario Teixeira <dario.teixeira@nleyten.com>
To: "David A. Harding" <dave@dtrt.org>
In-Reply-To: <20150217155011.GA5124@localhost.localdomain>
References: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com>
<cc1f451ed0bcad909d203ece06e1040a@nleyten.com>
<20150217155011.GA5124@localhost.localdomain>
Message-ID: <8e6661f5abc99f6b93787a1e6f34e965@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: 1YNnAO-0000ZK-OO
Cc: bitcoin-development@lists.sourceforge.net
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 18:46:42 -0000
Hi Dave,
> I'm the primary author of the Bitcoin.org JSON-RPC reference, and I'd
> be happy to help.
Thanks -- it is much appreciated!
> Do you think it would be possible for you to submit a minimal pull
> request against the docs adding the type information you need to just
> one RPC call? From there we can see how much work it would take to
> generalize that across all 100+ printed pages worth of RPC docs.
Sure, I would be glad to help. In fact, most of grunt work has
already been done for the OCaml-bitcoin API [1,2], which could be
used as a guide even if you don't use OCaml (beware that it may
contain errors, though).
Besides tweaking each RPC call, we would need to add a new section
to the docs, to be placed before the RPC calls. This List of
Types section would list all the custom types defined in the API,
providing a brief description for each and indicating the JSON type
used for serialisation (almost invariantly "string", I reckon).
But before I submit a pull request, allow me to exemplify with
AddMultiSigAddress:
Parameter #1: (no changes)
Parameter #2: I would keep "array" as the type of "Keys or
Addresses". If we follow the convention of using a pipe character to
represent unions, then the type for "Key or Address" is not "string",
but "public_key | p2pkh_address". This would also require adding
two entries to the List of Types section, describing public_key and
p2pkh_address, and letting the users know that they are serialised
as JSON strings. (Note that the precise type of "Keys or Addresses"
is actually "Array [public_key | p2pkh_address]". However, since
the type of each element is also listed, this info is redundant
and we can safely state it's just an array.)
Parameter #3: The type should be "account", obviously.
Result: a p2sh_address. If there is only one type of such P2SH
addresses and they can be used interchangeably, then this would
suffice. If however, there are actually several incompatible kinds
of P2SH address, then we'd need to be more precise about which one
we mean.
Thanks again for your time!
Kind regards,
Dario Teixeira
[1] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.ENGINE.html
[2] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.html
|
