diff --git a/btcjson/v2/btcjson/README.md b/btcjson/v2/btcjson/README.md new file mode 100644 index 00000000..bccb13fa --- /dev/null +++ b/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. diff --git a/btcjson/v2/btcjson/doc.go b/btcjson/v2/btcjson/doc.go new file mode 100644 index 00000000..6370fd75 --- /dev/null +++ b/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 Cmd) + - Notifications (type Ntfn) + - Response Objects (type Response) + - Result (type 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 NewCmd 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