btcjson: Add README.md and doc.go for btcjsonv2.

btcjson/v2/btcjson/README.md

@@ -0,0 +1,67 @@
+btcjson
+=======
+
+[![Build Status](https://travis-ci.org/btcsuite/btcd.png?branch=master)]
+(https://travis-ci.org/btcsuite/btcd) [![ISC License]
+(http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
+
+Package btcjson implements concrete types for marshalling to and from the
+bitcoin JSON-RPC API.  A comprehensive suite of tests is provided to ensure
+proper functionality.
+
+Although this package was primarily written for the btcsuite, it has
+intentionally been designed so it can be used as a standalone package for any
+projects needing to marshal to and from bitcoin JSON-RPC requests and responses.
+
+Note that although it's possible to use this package directly to implement an
+RPC client, it is not recommended since it is only intended as an infrastructure
+package.  Instead, RPC clients should use the
+[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package which provides
+a full blown RPC client with many features such as automatic connection
+management, websocket support, automatic notification re-registration on
+reconnect, and conversion from the raw underlying RPC types (strings, floats,
+ints, etc) to higher-level types with many nice and useful properties.
+
+## Documentation
+
+[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)]
+(http://godoc.org/github.com/btcsuite/btcd/btcjson/v2/btcjson)
+
+Full `go doc` style documentation for the project can be viewed online without
+installing this package by using the GoDoc site
+[here](http://godoc.org/github.com/btcsuite/btcd/btcjson/v2/btcjson).
+
+You can also view the documentation locally once the package is installed with
+the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
+http://localhost:6060/pkg/github.com/btcsuite/btcd/btcjson/v2/btcjson
+
+## Installation
+
+```bash
+$ go get github.com/btcsuite/btcd/btcjson/v2/btcjson
+```
+
+## GPG Verification Key
+
+All official release tags are signed by Conformal so users can ensure the code
+has not been tampered with and is coming from Conformal.  To verify the
+signature perform the following:
+
+- Download the public key from the Conformal website at
+  https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
+
+- Import the public key into your GPG keyring:
+  ```bash
+  gpg --import GIT-GPG-KEY-conformal.txt
+  ```
+
+- Verify the release tag with the following command where `TAG_NAME` is a
+  placeholder for the specific tag:
+  ```bash
+  git tag -v TAG_NAME
+  ```
+
+## License
+
+Package btcjson is licensed under the [copyfree](http://copyfree.org) ISC
+License.

btcjson/v2/btcjson/doc.go

@@ -0,0 +1,146 @@
+// Copyright (c) 2015 Conformal Systems LLC.
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+/*
+Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
+
+Overview
+
+When communicating via the JSON-RPC protocol, all of the commands need to be
+marshalled to and from the the wire in the appropriate format.  This package
+provides data structures and primitives to ease this process.
+
+In addition, it also provides some additional features such as custom command
+registration, command categorization, and reflection-based help generation.
+
+JSON-RPC Protocol Overview
+
+This information is not necessary in order to use this package, but it does
+provide some intuition into what the marshalling and unmarshalling that is
+discussed below is doing under the hood.
+
+As defined by the JSON-RPC spec, there are effectively two forms of messages on
+the wire:
+
+  - Request Objects
+    {"jsonrpc":"1.0","id":"SOMEID","method":"SOMEMETHOD","params":[SOMEPARAMS]}
+    NOTE: Notifications are the same format except the id field is null.
+
+  - Response Objects
+    {"result":SOMETHING,"error":null,"id":"SOMEID"}
+    {"result":null,"error":{"code":SOMEINT,"message":SOMESTRING},"id":"SOMEID"}
+
+For requests, the params field can vary in what it contains depending on the
+method (a.k.a. command) being sent.  Each parameter can be as simple as an int
+or a complex structure containing many nested fields.  The id field is used to
+identify a request and will be included in the associated response.
+
+When working with asynchronous transports, such as websockets, spontaneous
+notifications are also possible.  As indicated, they are the same as a request
+object, except they have the id field set to null.  Therefore, servers will
+ignore requests with the id field set to null, while clients can choose to
+consume or ignore them.
+
+Unfortunately, the original Bitcoin JSON-RPC API (and hence anything compatible
+with it) doesn't always follow the spec and will sometimes return an error
+string in the result field with a null error for certain commands.  However,
+for the most part, the error field will be set as described on failure.
+
+Marshalling and Unmarshalling
+
+Based upon the discussion above, it should be easy to see how the types of this
+package map into the required parts of the protocol
+
+  - Request Objects (type Request)
+    - Commands (type <Foo>Cmd)
+    - Notifications (type <Foo>Ntfn)
+  - Response Objects (type Response)
+    - Result (type <Foo>Result)
+
+To simplify the marshalling of the requests and responses, the MarshalCmd and
+MarshalResponse functions are provided.  They return the raw bytes ready to be
+sent across the wire.
+
+Unmarshalling a received Request object is a two step process:
+  1) Unmarshal the raw bytes into a Request struct instance via json.Unmarshal
+  2) Use UnmarshalCmd on the Result field of the unmarshalled Request to create
+     a concrete command or notification instance with all struct fields set
+     accordingly
+
+This approach is used since it provides the caller with access to the additional
+fields in the request that are not part of the command such as the ID.
+
+Unmarshalling a received Response object is also a two step process:
+  1) Unmarhsal the raw bytes into a Response struct instance via json.Unmarshal
+  2) Depending on the ID, unmarshal the Result field of the unmarshalled
+     Response to create a concrete type instance
+
+As above, this approach is used since it provides the caller with access to the
+fields in the response such as the ID and Error.
+
+Command Creation
+
+This package provides two approaches for creating a new command.  This first,
+and preferred, method is to use one of the New<Foo>Cmd functions.  This allows
+static compile-time checking to help ensure the parameters stay in sync with
+the struct definitions.
+
+The second approach is the NewCmd function which takes a method (command) name
+and variable arguments.  The function includes full checking to ensure the
+parameters are accurate according to provided method, however these checks are,
+obviously, run-time which means any mistakes won't be found until the code is
+actually executed.  However, it is quite useful for user-supplied commands
+that are intentionally dynamic.
+
+Custom Command Registration
+
+The command handling of this package is built around the concept of registered
+commands.  This is true for the wide variety of commands already provided by the
+package, but it also means caller can easily provide custom commands with all
+of the same functionality as the built-in commands.  Use the RegisterCmd
+function for this purpose.
+
+A list of all registered methods can be obtained with the RegisteredCmdMethods
+function.
+
+Command Inspection
+
+All registered commands are registered with flags that identify information such
+as whether the command applies to a chain server, wallet server, or is a
+notification along with the method name to use.  These flags can be obtained
+with the MethodUsageFlags flags, and the method can be obtained with the
+CmdMethod function.
+
+Help Generation
+
+To facilitate providing consistent help to users of the RPC server, this package
+exposes the GenerateHelp and function which uses reflection on registered
+commands or notifications, as well as the provided expected result types, to
+generate the final help text.
+
+In addition, the MethodUsageText function is provided to generate consistent
+one-line usage for registered commands and notifications using reflection.
+
+Errors
+
+There are 2 distinct type of errors supported by this package:
+
+  - General errors related to marshalling or unmarshalling or improper use of
+    the package (type Error)
+  - RPC errors which are intended to be returned across the wire as a part of
+    the JSON-RPC response (type RPCError)
+
+The first category of errors (type Error) typically indicates a programmer error
+and can be avoided by properly using the API.  Errors of this type will be
+returned from the various functions available in this package.  They identify
+issues such as unsupported field types, attempts to register malformed commands,
+and attempting to create a new command with an improper number of parameters.
+The specific reason for the error can be detected by type asserting it to a
+*btcjson.Error and accessing the ErrorCode field.
+
+The second category of errors (type RPCError), on the other hand, are useful for
+returning errors to RPC clients.  Consequently, they are used in the previously
+described Response type.
+*/
+package btcjson