Wallet protocol: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
← Older editNewer edit →
Luke-jr (talk | contribs)
Clerks, Administrators, Editors
3,074 edits
Luke-jr (talk | contribs)
Clerks, Administrators, Editors
3,074 edits
Post Draft 0 for commenting/critique
Line 26: Line 26:
=== UI bundling ===
=== UI bundling ===
For more secure use by ordinary end users, UIs and Wallets should support 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.
For more secure use by ordinary end users, UIs and Wallets should support 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.
= DRAFT 0 =
Everything beyond this point is strictly DRAFT, should NOT be implemented, and is subject to being completely rewritten or modified!
== Transport Layer ==
Must support at least reliable in-order stream data.
Such as:
* stdio (required for self-contained UI bundling)
* TLS (recommended)
* TCP (NOT recommended; see TLS)
* SSH
== Session Layer ==
HTTP or SPDY<ref name="SPDY"/>
== Presentation Layer ==
HTTP-with-SSE<ref name="SSE"/> request semantics
=== Formats ===
These content types may be specified in the Content-Type header, and Accept header.
* application/x-ripemd-160 (required)
* application/x-sha (required)
* multipart/mixed (required)
* text/event-stream<ref name="SSE"/> (required for events over HTTP)
* application/x-bitcoin (required wallet-side)
* application/json<ref name="RFC4627"/> (recommended)
* application/xml
== Application Layer ==
=== Security ===
Wallets may micro-manage security as they like, but the following are RECOMMENDED security levels:
{| class="wikitable"
| "Miner" || Can generate new addresses, get work, and report found blocks
|-
| 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 || Can administrate (download, destroy, etc) wallet keys
|}
=== Object/Query Schema ===
May be provided in multipart/mixed, JSON, XML, etc...
{| class="wikitable sortable"
! Field Name !! Blk !! Tx !! Accting !! Key !! Acct !! Queryable !! Description
|-
| id
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value Yes}}
| {{Table Value Yes}} || {{Table Value Yes}}
| {{Table Value Yes}}
| Unique data identifier; only guaranteed to remain the same for a single session
|-
| type
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value Yes}}
| {{Table Value Yes}} || {{Table Value Yes}}
| {{Table Value Yes}}
| Type of data: 'key', 'tx', 'block', 'account', 'accounting'
|-
| hash
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value No}}
| {{Table Value Yes}} || {{Table Value No}}
| {{Table Value Yes}}
|-
| size
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value Unknown}}
| {{Table Value Yes}} || {{Table Value Unknown}}
| {{Table Value Yes}}
|-
| time
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value Yes}}
| {{Table Value No}} || {{Table Value No}}
| {{Table Value Yes}}
|-
| difficulty
| {{Table Value Yes}} || {{Table Value No}} || {{Table Value No}}
| {{Table Value No}} || {{Table Value No}}
| {{Table Value Yes}}
|-
| related
| {{Table Value Yes}} || {{Table Value Yes}} || {{Table Value Unknown}}
| {{Table Value Unknown}} || {{Table Value Unknown}}
| {{Table Value Unknown}}
| Can have multiple entries (in JSON, an array value)
|-
| coinbase
| {{Table Value No}} || {{Table Value Yes}} || {{Table Value No}}
| {{Table Value No}} || {{Table Value No}}
| {{Table Value Yes}}
|-
| inputs
| {{Table Value No}} || {{Table Value Yes}} || {{Table Value Unknown}}
| {{Table Value No}} || {{Table Value No}}
| {{Table Value Yes}}
|-
| outputs
| {{Table Value No}} || {{Table Value Yes}} || {{Table Value Unknown}}
| {{Table Value No}} || {{Table Value No}}
| {{Table Value Yes}}
|}
=== Data ===
* 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
=== Requests ===
==== Data Search ====
* 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.
==== Monitor Events ====
* Always POST
===== New Data Available =====
* Query
=== Events ===
==== New Data Available ====
== References ==
<references>
<ref name="RFC4627">[http://tools.ietf.org/html/rfc4627 The application/json Media Type for JavaScript Object Notation (JSON)], D. Crockford. JSON.org.</ref>
<ref name="SSE">[http://dev.w3.org/html5/eventsource/ Server-Sent Events], Ian Hickson, Google, Inc.</ref>
<ref name="SPDY">[http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft2 SPDY Protocol], various. Google, Inc.</ref>
</references>

Revision as of 17:31, 21 March 2011

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".

Explanation

Please see the Infrastructure page for an idea of where this protocol fits into the big picture.

Requirements

  • 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

Debates

Binary or plaintext

  • Binary is more efficient to parse and create
  • Plaintext is easier for humans to debug
  • 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

Cooperative mining

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.

UI bundling

For more secure use by ordinary end users, UIs and Wallets should support 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.

DRAFT 0

Everything beyond this point is strictly DRAFT, should NOT be implemented, and is subject to being completely rewritten or modified!

Transport Layer

Must support at least reliable in-order stream data.

Such as:

  • stdio (required for self-contained UI bundling)
  • TLS (recommended)
  • TCP (NOT recommended; see TLS)
  • SSH

Session Layer

HTTP or SPDY[1]

Presentation Layer

HTTP-with-SSE[2] request semantics

Formats

These content types may be specified in the Content-Type header, and Accept header.

  • application/x-ripemd-160 (required)
  • application/x-sha (required)
  • multipart/mixed (required)
  • text/event-stream[2] (required for events over HTTP)
  • application/x-bitcoin (required wallet-side)
  • application/json[3] (recommended)
  • application/xml

Application Layer

Security

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
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 Can administrate (download, destroy, etc) wallet keys

Object/Query Schema

May be provided in multipart/mixed, JSON, XML, etc...

Field Name Blk Tx Accting Key Acct Queryable Description
id 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 Type of data: 'key', 'tx', 'block', 'account', 'accounting'
hash Yes Yes No Yes No Yes
size Yes Yes ?? Yes ?? Yes
time Yes Yes Yes No No Yes
difficulty Yes No No No No Yes
related Yes Yes ?? ?? ?? ?? Can have multiple entries (in JSON, an array value)
coinbase No Yes No No No Yes
inputs No Yes ?? No No Yes
outputs No Yes ?? No No Yes

Data

  • 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

Requests

Data Search

  • 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.

Monitor Events

  • Always POST
New Data Available
  • Query

Events

New Data Available

References

  1. ↑ SPDY Protocol, various. Google, Inc.
  2. ↑ 2.0 2.1 Server-Sent Events, Ian Hickson, Google, Inc.
  3. ↑ The application/json Media Type for JavaScript Object Notation (JSON), D. Crockford. JSON.org.
Retrieved from "https://en.bitcoin.it/w/index.php?title=Wallet_protocol&oldid=5744"