btcrpc

README

go-btcrpc

go-btcrpc is a Go library use for interacting to the bitcoin node from your server with JSON-RPC which is a standard protocol for blockchain.

This library provides the easiest way to send JSON-RPC.

Installation

Use go get to install and update.

go get github.com/KeisukeYamashita/go-btcrpc.git

Setup

You need to setup environmental variables.

Firstly, copy the .env.sample as .env

cp .env.sample .env

Setup in your .env.

BTCD_ENDPOINT: NODE_ENDPOINT
USERNAME: USERNAME_FOR_BASICAUTH
PASSWORD: PASSWORD_FOR_BASICAUTH

Usage and Example

This shows you that easiest request to the node which is getting the infos.

package main

import (
  "fmt"
  btcrpc "github.com/KeisukeYamashita/go-btcrpc"
  )

func main() {
	basicAuth := &BasicAuth{
		Username: os.Getenv("USERNAME"),
		Password: os.Getenv("PASSWORD"),
	}
	c := NewRPCClient(os.Getenv("BTCD_ENDPOINT"), basicAuth)
	address := "my88QLpf2RYYDdNMmDwYvfx6TFc6NXaELa"
	balance := c.GetBalance(address)
	fmt.Print(balance) // 0.13514 BTC
}

Equal curl command

curl -X "POST" "<YOUR_BITCOIN_NODE>" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u '<YOUR_USER_NAME>:<YOUR_PASSWORD>' \
     -d $'{
  "method": "getbalance",
  "id": "1",
  "params": [
    "my88QLpf2RYYDdNMmDwYvfx6TFc6NXaELa"
  ]
}'

It'll return a JSON.

Available Methods

method	discription
getNewAddress	creates a new address to your account.
getBalance	get the balance of your address.
getBlockHash	get the hash of the block.
getBlock	get the block by hash of the block.
getBlockCount	get the newest block count by hash of the block.
decodeTransaction	decode the raw transaction to humanreadable transaction by hash of the block.
getrawTransaction	get the raw transaction hash block count by hash of the block.

Use tests

Set up your environmental valiables in .env to conduct this test.

cp .env.sample .env

Then write in your endpoint in this file.

Finally run your test. It will pass if your bitcoin node is setted up correctly.

GO_ENV = test go test btcrpc

Contribution

To contribute, just send me a pull request! If it is valid, you will be added on the contribution doc in /doc/contributor.md .

License

Copyright 2017 Keisuke Yamashita.

Licensed under the Apache 2.0 license.

Documentation

Overview

Package btcrpc implements RPC methods to interact with the bitcoin node bitcoind. See informations in the pages link below about Bitcoin development. https://bitcoin.org/en/development

Index

• type BasicAuth
• type Block
• type RPCClient
  • func NewRPCClient(endpoint string, basicAuth *BasicAuth) *RPCClient
  • func (c *RPCClient) DecodeRawTransactions(rawTxs []string) ([]*Transaction, error)
  • func (c *RPCClient) GetBalance(address string) (float32, error)
  • func (c *RPCClient) GetBlock(h string) (*Block, error)
  • func (c *RPCClient) GetBlockCount() (int32, error)
  • func (c *RPCClient) GetBlockHash(height int32) (string, error)
  • func (c *RPCClient) GetNewAddress(account string) (string, error)
  • func (c *RPCClient) GetRawTransactions(txids []string) ([]string, error)
• type RPCer
• type ScriptPubKey
• type ScriptSig
• type Transaction
• type Vin
• type VinCoinbaseTransaction
• type VinTransaction
• type Vout

Types

type BasicAuth

type BasicAuth struct {
	Username string
	Password string
}

BasicAuth is for Bitcoin Node supports basic auth. Some nodes do not need this. In that case, leave these blank.

type Block

type Block struct {
	Hash          string   `json:"hash"`
	Version       int32    `json:"version"`
	Txs           []string `json:"txs"`
	Time          int32    `json:"time"`
	Size          int32    `json:"size"`
	Nonce         int32    `json:"nonce"`
	Weight        int32    `json:"weight"`
	VersionHex    string   `json:"versionHex"`
	Difficulty    int32    `json:"difficulty"`
	Mediantime    int32    `json:"mediantime"`
	Chainwork     string   `json:"chainwork"`
	Strippedsize  int32    `json:"strippedsize"`
	Merkleroot    string   `json:"merkleroot"`
	Bits          string   `json:"bits"`
	NextBlockhash string   `json:"nextBlockhash"`
	Confirmations int32    `json:"confirmations"`
	Height        int32    `json:"height"`
}

Block ...

type RPCClient

type RPCClient struct {
	*jsonrpc.RPCClient
}

RPCClient ...

func NewRPCClient

func NewRPCClient(endpoint string, basicAuth *BasicAuth) *RPCClient

NewRPCClient creates JSONRPC clients for your bitcoin node.

func (*RPCClient) DecodeRawTransactions

func (c *RPCClient) DecodeRawTransactions(rawTxs []string) ([]*Transaction, error)

DecodeRawTransactions decodes the raw transactions to human readable transactions.

func (*RPCClient) GetBalance

func (c *RPCClient) GetBalance(address string) (float32, error)

GetBalance gets the balance of the address. It is only possible to get the balance which is made by this node, otherwise it will return 0.00.

func (*RPCClient) GetBlock

func (c *RPCClient) GetBlock(h string) (*Block, error)

GetBlock gets the block information associated with the block hash(id). It contains a lot of infos about transactions.

func (*RPCClient) GetBlockCount

func (c *RPCClient) GetBlockCount() (int32, error)

GetBlockCount gets the latest block height. Note that The methods name is "Count" not "Height".

func (*RPCClient) GetBlockHash

func (c *RPCClient) GetBlockHash(height int32) (string, error)

GetBlockHash gets the block hash(id) associated with the block height.

func (*RPCClient) GetNewAddress

func (c *RPCClient) GetNewAddress(account string) (string, error)

GetNewAddress gets new address associated with the account name given. If the account name is blank(nil), if will also returns a addresss with no associated account.

func (*RPCClient) GetRawTransactions

func (c *RPCClient) GetRawTransactions(txids []string) ([]string, error)

GetRawTransactions gets the raw transactions associated with the transaction hashes(ids).

type RPCer

type RPCer interface {
	GetBlockHash(height int32) (string, error)
}

RPCer ...

type ScriptPubKey

type ScriptPubKey struct {
	Asm       string   `json:"asm"`
	Hex       string   `json:"hex"`
	ReqSigs   int32    `json:"reqSigs"`
	Type      string   `json:"type"`
	Addresses []string `json:"addresses"`
}

ScriptPubKey ...

type ScriptSig

type ScriptSig struct {
	Asm string `json:"asm"`
	Hex string `json:"hex"`
}

ScriptSig ...

type Transaction

type Transaction struct {
	Txid     string `json:"txid"`
	Hash     string `json:"hash"`
	Version  int32  `json:"id"`
	Size     int32  `json:"size"`
	Vsize    int32  `json:"vsize"`
	Locktime int32  `json:"locktime"`
	Vins     Vin
	Vouts    []Vout
}

Transaction ...

type Vin

type Vin map[int]interface{}

Vin ...

type VinCoinbaseTransaction

type VinCoinbaseTransaction struct {
	Coinbase string `json:"coinbase"`
	Sequence int64  `json:"sequence"`
}

VinCoinbaseTransaction is a struct of Vins(inputs) with mining.

type VinTransaction

type VinTransaction struct {
	Txid        string `json:"txid"`
	Vout        int32  `json:"vout"`
	ScriptSig   ScriptSig
	TxinWitness []string `json:"txinWitness"`
	Sequence    int64    `json:"Sequence"`
}

VinTransaction is a struct of Vin(inputs) with normal transaction.

type Vout

type Vout struct {
	Value        float32 `json:"value"`
	N            int32   `json:"n"`
	ScriptPubKey ScriptPubKey
}

Vout ...