This is a project to define a new wallet protocol addressing problems with the current JSON-RPC implementation in bitcoind. Please feel free to make edits. If you disagree with something, turn it into a "debate".
- 1 Explanation
- 2 Requirements
- 3 DRAFT 0
- 3.1 Conformance requirements
- 3.2 Transport Layer
- 3.3 Session Layer
- 3.4 Presentation Layer
- 3.5 Application Layer
- 3.5.1 Security
- 3.5.2 Object/Query Schema
- 3.5.3 Data
- 3.5.4 Information
- 3.5.5 Requests
- 3.5.6 Events
- 3.5.7 p2p protocol encapsulation
- 3.6 Appendix A. Useful algorithms
- 3.7 Appendix B. JSON-RPC equivalents
- 3.7.1 backupwallet
- 3.7.2 getaccount / getlabel
- 3.7.3 getaddressesbyaccount / getaccountaddress / getaddressesbylabel
- 3.7.4 getbalance
- 3.7.5 getblockcount / getblocknumber
- 3.7.6 getconnectioncount
- 3.7.7 getdifficulty
- 3.7.8 getgenerate
- 3.7.9 gethashespersec
- 3.7.10 getinfo
- 3.7.11 getnewaddress
- 3.7.12 getreceivedbyaccount / getreceivedbylabel
- 3.7.13 getreceivedbyaddress / getamountreceived
- 3.7.14 gettransaction
- 3.7.15 getwork
- 3.7.16 help
- 3.7.17 listaccounts
- 3.7.18 listreceivedbyaccount / listreceivedbylabel
- 3.7.19 listreceivedbyaddress / getallreceived
- 3.7.20 listtransactions
- 3.7.21 move
- 3.7.22 sendfrom
- 3.7.23 sendtoaddress
- 3.7.24 setaccount / setlabel
- 3.7.25 setgenerate
- 3.7.26 settxfee
- 3.7.27 stop
- 3.7.28 validateaddress
- 3.8 References
This protocol aims to be a standard for communication between Wallets and User Interfaces. It can be used to access a Wallet remotely, or even locally, even if the Wallet and User Interface are produced by different or competing vendors. For example, you could use an Android User Interface from Google to control a QBitcoin Wallet.
Please see the Infrastructure page for an overview of where this protocol fits into the big picture.
- Never use human-formatted data (for example, use base bitcoin units, not Decimal BitCoins nor Tonal BitCoins, which should only be used in formatting for humans)
- Don't require polling (for example, broadcast events for new transactions, or changes to current "work")
- Cooperative mining (see below)
- Allow calculating expected minimum fee for transactions, with either (wallet's choice) locking on the used inputs, or prebuilding the tx and error if it becomes invalid before sending
- Easy to use in a RPC-like manner, for simple applications
Binary or plaintext
- Binary is more efficient to parse and create
- Plaintext is easier for humans to debug, and avoids forming a dependency on a specific number of bits, endianness, or precision
- Binary can include custom transactions as-is for transmission
- Protobuf (binary) seems efficient and easy to use from all major languages
- JSON implementations tend to be buggy
The protocol should support submitting completed blocks, such that it can get (just) addresses from an upstream pool to generate to, and send all completed blocks to that pool for verification and counting (and possibly submission to the network). This can reduce the pool's load.
For more secure use by ordinary end users, UIs and Wallets should support stream-based communication over standard I/O (stdio). This allows the UI to simply execute a dedicated Wallet, without requiring the user to setup Wallet-side authentication. This also permits full compatibility with a hardware-based wallet located on a secured device (for example, a cryptographic hardware module, or a wallet device connected via RS232 or USB). (Suggestion, if UI's could talk to any stream, including a child process's stdio, as well as a pipe or a device, the flexibility would be valuable)
Everything beyond this point is strictly DRAFT, should NOT be implemented, and is subject to being completely rewritten or modified!
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Must support at least reliable in-order stream data.
- stdio (required for self-contained UI bundling)
- TLS (recommended)
- TCP (NOT recommended; see TLS)
Consideration: There are many ways to communicate that are desirable for payment processing but which don't inherently offer TCP-like sequencing, specifically things that act like or run over serial ports (including bluetooth, infrared, possibly NFC). Some mediums like this are prone to corrupting or dropping data, but fortunately mediums like this are also unlikely to deliver data out of sequence. Some sort of simple error checking and packetizing of messages (even as simple as CRC-16 with STX+ETX wrappers as used in today's payment processing industry) should be required on all serial-like connections.
HTTP-with-SSE request semantics
- GET for read-only access
- POST for methods (or complex read-only)
- PUT for uploads
- HEAD for metadata
These content types may be specified in the Content-Type header, and Accept header.
- application/x-www-form-urlencoded (required)
- application/x-ripemd-160 (required)
- application/x-sha (required)
- multipart/mixed (required)
- text/event-stream (required for events over HTTP)
- application/x-bitcoin (required wallet-side)
- application/json (recommended)
Wallets may micro-manage security as they like, but the following are RECOMMENDED security levels:
|"Miner"||Can generate new addresses, get work, and report found blocks|
|Merchant||Can create a transaction (only with 'proposal' flag), but not send it without user interaction|
|Read-only||Can view accounts, addresses, and any public data, and combinations thereof (eg, balances)|
|Financial||Can create new transactions using the wallet's keys|
|Full/Admin||Can administrate (download, destroy, etc) wallet keys|
Wallets MAY grant full access to username 'admin' with a null password, to requests over stdio.
Wallets with user interactivity (e.g. smartphones) SHOULD grant Merchant access to username 'merchant' will a null password, to requests made over direct (ie, physically local, like Bluetooth) connections. User interfaces SHOULD monitor for new, unsigned transactions with the 'proposal' flag set, and prompt the user to sign or delete them. If the wallet is non-interactive (a server daemon for example), Merchant access SHOULD be disallowed.
Suggestion: there should also be provisions for PKI in place, so that Joe Walletholder knows he is paying 7-Eleven, a Japanese-owned company, rather than the 7-Eleven clerk, a divorced Wisconsin man. Such PKI should be functional independent of TLS (which might not be available or commonly implemented over serial-like connections like Bluetooth)
May be provided in multipart/mixed, JSON, XML, etc...
|id||Yes||Yes||Yes||Yes||Yes||Yes||Yes||Unique data identifier; only guaranteed to remain the same for a single session|
|type||Yes||Yes||Yes||Yes||Yes||Yes||Yes||Type of data: 'key', 'tx', 'coin', 'block', 'account', 'accounting'|
|accepted||??||Yes||??||Yes||No||No||Yes||An unconfirmed, accepted tx, is part of the current mining merkle tree|
|related||Yes||Yes||??||??||??||??||Yes||Can have multiple entries (in JSON, an array value)|
|network||Yes||Yes||??||Yes||Yes||??||Yes||0xF9BEB4D9 for the main network; 0xFABFB5DA for testnet|
- Arbitrary data can be accessed with the path /data/<id>
- GET to fetch
- To get only block header, use /data/<id>/header
- To get only actual content (eg, no calculated values), use /data/<id>/raw
- Optional: PUT to upload
- GET /state/<network>/connections
- Mining info: (required for mining support)
- GET /state/<network>/hashesPerSec (optional)
- GET /state/<network>/merkle
- GET /info/protocols
- Returns a list of supported protocols/versions and their URIs
- GET /validate/address?network=<id>&address=<hash>
- GET /balance?<query-object>
Match transactions to be included in the balance. To ignore spends, use matching.
- GET /dataSearch?<query-object>
- POST /dataSearch allowed for more complex queries
NOTE: To get the id rather than the data itself, use a HEAD request and check the Location header.
Generate new address
- POST /newAddress
- Optional parameter: recycle (bool) -- allows wallet to reuse a spent change address; if not supported, wallet should silently ignore
- Optional parameter: generate (bool) -- if true, make a new address on the spot, never use a preexisting one; if not supported, throw an error
- Optional parameter: account -- associate new address funds with this account id
- Always POST
New data available
Move between accounts
- POST /accounting/move
- query=<query-object> OR amount=<amount>
- Optional: comment=<string>
- POST /tx/new
- send (bool) -- If true, sign and broadcast the transaction immediately
- fee (amount or range) -- If range, the wallet will try to calculate the minimum it expects the network to accept; if omitted, automatic fee range is unlimited unless bound by other factors (eg, input+strict)
- Optional: fromAccount (account id)
- Optional: input (multiple allowed of: coin id, OR coin id=>scriptSig)
- output (multiple allowed of: address=>amount pairs, OR script=>amount)
- strict (bool) -- If set, error rather than vary any parameters
- Optional: comment=<string>
- POST /tx/send?id=<existing-tx-internal-id>
- POST /shutdown
New Data Available
p2p protocol encapsulation
Optional: Establish a WebSocket connection to /p2p to speak direct p2p protocol
Appendix A. Useful algorithms
Because numerous (most) transactions change confirmation at the same event, the only way to do this efficiently, is to monitor for new block events. When a block arrives, increment the confirmation count of all transactions with at least 1 confirmation already. Then check the new block's introduced transactions (incrementing them from 0 to 1), and delete/invalidate any revoked transactions (eg, from a competing chain).
Appendix B. JSON-RPC equivalents
getaccount / getlabel
getaddressesbyaccount / getaccountaddress / getaddressesbylabel
getblockcount / getblocknumber
getreceivedbyaccount / getreceivedbylabel
getreceivedbyaddress / getamountreceived
listreceivedbyaccount / listreceivedbylabel
listreceivedbyaddress / getallreceived
setaccount / setlabel
- Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.
- Hypertext Transfer Protocol -- HTTP/1.1, Fielding, et al, W3C.
- SPDY Protocol, various. Google, Inc.
- Server-Sent Events, Ian Hickson, Google, Inc.
- Extensible Markup Language (XML) 1.0 (Second Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen and Eve Maler, W3C.