From 03a8bf2eb4b5c151f84ecefb34a81e6d28742799 Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 24 Jan 2017 18:18:48 -0700 Subject: [PATCH] btcjson/docs: add `rescanblocks` command backported from dcrd --- btcjson/chainsvrwscmds.go | 23 ++++++++++++++ btcjson/chainsvrwscmds_test.go | 14 +++++++++ btcjson/chainsvrwsntfns.go | 23 ++++++++++---- btcjson/chainsvrwsresults.go | 13 +++++++- btcjson/chainsvrwsresults_test.go | 50 +++++++++++++++++++++++++++++++ docs/json_rpc_api.md | 26 ++++++++++++---- 6 files changed, 137 insertions(+), 12 deletions(-) create mode 100644 btcjson/chainsvrwsresults_test.go diff --git a/btcjson/chainsvrwscmds.go b/btcjson/chainsvrwscmds.go index 7a57ea59..bf973e25 100644 --- a/btcjson/chainsvrwscmds.go +++ b/btcjson/chainsvrwscmds.go @@ -178,6 +178,8 @@ func NewStopNotifySpentCmd(outPoints []OutPoint) *StopNotifySpentCmd { } // RescanCmd defines the rescan JSON-RPC command. +// +// NOTE: Deprecated. Use RescanBlocksCmd instead. type RescanCmd struct { BeginBlock string Addresses []string @@ -190,6 +192,8 @@ type RescanCmd struct { // // The parameters which are pointers indicate they are optional. Passing nil // for optional parameters will use the default value. +// +// NOTE: Deprecated. Use NewRescanBlocksCmd instead. func NewRescanCmd(beginBlock string, addresses []string, outPoints []OutPoint, endBlock *string) *RescanCmd { return &RescanCmd{ BeginBlock: beginBlock, @@ -199,6 +203,24 @@ func NewRescanCmd(beginBlock string, addresses []string, outPoints []OutPoint, e } } +// RescanBlocksCmd defines the rescan JSON-RPC command. +// +// NOTE: This is a btcd extension ported from github.com/decred/dcrd/dcrjson +// and requires a websocket connection. +type RescanBlocksCmd struct { + // Block hashes as a string array. + BlockHashes []string +} + +// NewRescanBlocksCmd returns a new instance which can be used to issue a rescan +// JSON-RPC command. +// +// NOTE: This is a btcd extension ported from github.com/decred/dcrd/dcrjson +// and requires a websocket connection. +func NewRescanBlocksCmd(blockHashes []string) *RescanBlocksCmd { + return &RescanBlocksCmd{BlockHashes: blockHashes} +} + func init() { // The commands in this file are only usable by websockets. flags := UFWebsocketOnly @@ -215,4 +237,5 @@ func init() { MustRegisterCmd("stopnotifyspent", (*StopNotifySpentCmd)(nil), flags) MustRegisterCmd("stopnotifyreceived", (*StopNotifyReceivedCmd)(nil), flags) MustRegisterCmd("rescan", (*RescanCmd)(nil), flags) + MustRegisterCmd("rescanblocks", (*RescanBlocksCmd)(nil), flags) } diff --git a/btcjson/chainsvrwscmds_test.go b/btcjson/chainsvrwscmds_test.go index fce0c430..b0cd63cc 100644 --- a/btcjson/chainsvrwscmds_test.go +++ b/btcjson/chainsvrwscmds_test.go @@ -213,6 +213,20 @@ func TestChainSvrWsCmds(t *testing.T) { OutPoints: []btcjson.OutPoint{{Hash: "0000000000000000000000000000000000000000000000000000000000000123", Index: 0}}, }, }, + { + name: "rescanblocks", + newCmd: func() (interface{}, error) { + return btcjson.NewCmd("rescanblocks", `["0000000000000000000000000000000000000000000000000000000000000123"]`) + }, + staticCmd: func() interface{} { + blockhashes := []string{"0000000000000000000000000000000000000000000000000000000000000123"} + return btcjson.NewRescanBlocksCmd(blockhashes) + }, + marshalled: `{"jsonrpc":"1.0","method":"rescanblocks","params":[["0000000000000000000000000000000000000000000000000000000000000123"]],"id":1}`, + unmarshalled: &btcjson.RescanBlocksCmd{ + BlockHashes: []string{"0000000000000000000000000000000000000000000000000000000000000123"}, + }, + }, } t.Logf("Running %d tests", len(tests)) diff --git a/btcjson/chainsvrwsntfns.go b/btcjson/chainsvrwsntfns.go index 9c574f79..1f156234 100644 --- a/btcjson/chainsvrwsntfns.go +++ b/btcjson/chainsvrwsntfns.go @@ -47,13 +47,18 @@ const ( // FilteredBlockConnectedNtfnMethod instead. RedeemingTxNtfnMethod = "redeemingtx" - // RescanFinishedNtfnMethod is the method used for notifications from - // the chain server that a rescan operation has finished. + // RescanFinishedNtfnMethod is the legacy, deprecated method used for + // notifications from the chain server that a legacy, deprecated rescan + // operation has finished. + // + // NOTE: Deprecated. Not used with rescanblocks command. RescanFinishedNtfnMethod = "rescanfinished" - // RescanProgressNtfnMethod is the method used for notifications from - // the chain server that a rescan operation this is underway has made - // progress. + // RescanProgressNtfnMethod is the legacy, deprecated method used for + // notifications from the chain server that a legacy, deprecated rescan + // operation this is underway has made progress. + // + // NOTE: Deprecated. Not used with rescanblocks command. RescanProgressNtfnMethod = "rescanprogress" // TxAcceptedNtfnMethod is the method used for notifications from the @@ -199,6 +204,8 @@ func NewRedeemingTxNtfn(hexTx string, block *BlockDetails) *RedeemingTxNtfn { } // RescanFinishedNtfn defines the rescanfinished JSON-RPC notification. +// +// NOTE: Deprecated. Not used with rescanblocks command. type RescanFinishedNtfn struct { Hash string Height int32 @@ -207,6 +214,8 @@ type RescanFinishedNtfn struct { // NewRescanFinishedNtfn returns a new instance which can be used to issue a // rescanfinished JSON-RPC notification. +// +// NOTE: Deprecated. Not used with rescanblocks command. func NewRescanFinishedNtfn(hash string, height int32, time int64) *RescanFinishedNtfn { return &RescanFinishedNtfn{ Hash: hash, @@ -216,6 +225,8 @@ func NewRescanFinishedNtfn(hash string, height int32, time int64) *RescanFinishe } // RescanProgressNtfn defines the rescanprogress JSON-RPC notification. +// +// NOTE: Deprecated. Not used with rescanblocks command. type RescanProgressNtfn struct { Hash string Height int32 @@ -224,6 +235,8 @@ type RescanProgressNtfn struct { // NewRescanProgressNtfn returns a new instance which can be used to issue a // rescanprogress JSON-RPC notification. +// +// NOTE: Deprecated. Not used with rescanblocks command. func NewRescanProgressNtfn(hash string, height int32, time int64) *RescanProgressNtfn { return &RescanProgressNtfn{ Hash: hash, diff --git a/btcjson/chainsvrwsresults.go b/btcjson/chainsvrwsresults.go index 12968496..906b8fe4 100644 --- a/btcjson/chainsvrwsresults.go +++ b/btcjson/chainsvrwsresults.go @@ -1,4 +1,5 @@ -// Copyright (c) 2015 The btcsuite developers +// Copyright (c) 2015-2017 The btcsuite developers +// Copyright (c) 2015-2017 The Decred developers // Use of this source code is governed by an ISC // license that can be found in the LICENSE file. @@ -8,3 +9,13 @@ package btcjson type SessionResult struct { SessionID uint64 `json:"sessionid"` } + +// RescannedBlock contains the hash and all discovered transactions of a single +// rescanned block. +// +// NOTE: This is a btcsuite extension ported from +// github.com/decred/dcrd/dcrjson. +type RescannedBlock struct { + Hash string `json:"hash"` + Transactions []string `json:"transactions"` +} diff --git a/btcjson/chainsvrwsresults_test.go b/btcjson/chainsvrwsresults_test.go new file mode 100644 index 00000000..b1e17450 --- /dev/null +++ b/btcjson/chainsvrwsresults_test.go @@ -0,0 +1,50 @@ +// Copyright (c) 2017 The btcsuite developers +// Copyright (c) 2017 The Decred developers +// Use of this source code is governed by an ISC +// license that can be found in the LICENSE file. + +package btcjson_test + +import ( + "encoding/json" + "testing" + + "github.com/btcsuite/btcd/btcjson" +) + +// TestChainSvrWsResults ensures any results that have custom marshalling +// work as inteded. +func TestChainSvrWsResults(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + result interface{} + expected string + }{ + { + name: "RescannedBlock", + result: &btcjson.RescannedBlock{ + Hash: "blockhash", + Transactions: []string{"serializedtx"}, + }, + expected: `{"hash":"blockhash","transactions":["serializedtx"]}`, + }, + } + + t.Logf("Running %d tests", len(tests)) + for i, test := range tests { + marshalled, err := json.Marshal(test.result) + if err != nil { + t.Errorf("Test #%d (%s) unexpected error: %v", i, + test.name, err) + continue + } + if string(marshalled) != test.expected { + t.Errorf("Test #%d (%s) unexpected marhsalled data - "+ + "got %s, want %s", i, test.name, marshalled, + test.expected) + continue + } + } +} diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md index 6f165acb..cdcc4b93 100644 --- a/docs/json_rpc_api.md +++ b/docs/json_rpc_api.md @@ -694,11 +694,12 @@ user. Click the method name for further details such as parameter and return in |5|[stopnotifyreceived](#stopnotifyreceived)|*DEPRECATED, for similar functionality see [loadtxfilter](#loadtxfilter)*
Cancel registered notifications for when a txout spends to any of the passed addresses.|None| |6|[notifyspent](#notifyspent)|*DEPRECATED, for similar functionality see [loadtxfilter](#loadtxfilter)*
Send notification when a txout is spent.|[redeemingtx](#redeemingtx)| |7|[stopnotifyspent](#stopnotifyspent)|*DEPRECATED, for similar functionality see [loadtxfilter](#loadtxfilter)*
Cancel registered spending notifications for each passed outpoint.|None| -|8|[rescan](#rescan)|Rescan block chain for transactions to addresses and spent transaction outpoints.|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished) | +|8|[rescan](#rescan)|*DEPRECATED, for similar functionality see [rescanblocks](#rescanblocks)*
Rescan block chain for transactions to addresses and spent transaction outpoints.|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished) | |9|[notifynewtransactions](#notifynewtransactions)|Send notifications for all new transactions as they are accepted into the mempool.|[txaccepted](#txaccepted) or [txacceptedverbose](#txacceptedverbose)| |10|[stopnotifynewtransactions](#stopnotifynewtransactions)|Stop sending either a txaccepted or a txacceptedverbose notification when a new transaction is accepted into the mempool.|None| |11|[session](#session)|Return details regarding a websocket client's current connection.|None| |12|[loadtxfilter](#loadtxfilter)|Load, add to, or reload a websocket client's transaction filter for mempool transactions, new blocks and rescanblocks.|[relevanttxaccepted](#relevanttxaccepted)| +|13|[rescanblocks](#rescanblocks)|Rescan blocks for transactions matching the loaded transaction filter.|None| **7.2 Method Details**
@@ -799,7 +800,7 @@ user. Click the method name for further details such as parameter and return in |Method|rescan| |Notifications|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished)| |Parameters|1. BeginBlock (string, required) block hash to begin rescanning from
2. Addresses (JSON array, required)
 `[ (json array of strings)`
  `"bitcoinaddress", (string) the bitcoin address`
  `...`
 `]`
3. Outpoints (JSON array, required)
 `[ (JSON array)`
  `{ (JSON object)`
   `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`
   `"index":n (numeric) the txout index of the outpoint`
  `},`
  `...`
 `]`
4. EndBlock (string, optional) hash of final block to rescan| -|Description|Rescan block chain for transactions to addresses, starting at block BeginBlock and ending at EndBlock. The current known UTXO set for all passed addresses at height BeginBlock should included in the Outpoints argument. If EndBlock is omitted, the rescan continues through the best block in the main chain. Additionally, if no EndBlock is provided, the client is automatically registered for transaction notifications for all rescanned addresses and the final UTXO set. Rescan results are sent as recvtx and redeemingtx notifications. This call returns once the rescan completes.| +|Description|*DEPRECATED, for similar functionality see [rescanblocks](#rescanblocks)*
Rescan block chain for transactions to addresses, starting at block BeginBlock and ending at EndBlock. The current known UTXO set for all passed addresses at height BeginBlock should included in the Outpoints argument. If EndBlock is omitted, the rescan continues through the best block in the main chain. Additionally, if no EndBlock is provided, the client is automatically registered for transaction notifications for all rescanned addresses and the final UTXO set. Rescan results are sent as recvtx and redeemingtx notifications. This call returns once the rescan completes.| |Returns|Nothing| [Return to Overview](#WSExtMethodOverview)
@@ -856,6 +857,19 @@ user. Click the method name for further details such as parameter and return in |Returns|Nothing| [Return to Overview](#WSExtMethodOverview)
+*** + + + +| | | +|---|---| +|Method|rescanblocks| +|Notifications|None| +|Parameters|1. Blockhashes (JSON array, required) - List of hashes to rescan. Each next block must be a child of the previous.| +|Description|Rescan blocks for transactions matching the loaded transaction filter.| +|Returns|`[ (JSON array)`
  `{ (JSON object)`
    `"hash": "data", (string) Hash of the matching block.`
    `"transactions": [ (JSON array) List of matching transactions, serialized and hex-encoded.`
      `"serializedtx" (string) Serialized and hex-encoded transaction.`
    `]`
  `}`
`]`| +|Example Return|`[`
  `{`
    `"hash": "0000002099417930b2ae09feda10e38b58c0f6bb44b4d60fa33f0e000000000000000000d53...",`
    `"transactions": [`
      `"493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8..."`
    `]`
  `}`
`]`| + ### 8. Notifications (Websocket-specific) @@ -875,8 +889,8 @@ The following is an overview of the JSON-RPC notifications used for Websocket co |4|[redeemingtx](#redeemingtx)|*DEPRECATED, for similar functionality see [relevanttxaccepted](#relevanttxaccepted) and [filteredblockconnected](#filteredblockconnected)*
Processed a transaction that spends a registered outpoint.|[notifyspent](#notifyspent) and [rescan](#rescan)| |5|[txaccepted](#txaccepted)|Received a new transaction after requesting simple notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)| |6|[txacceptedverbose](#txacceptedverbose)|Received a new transaction after requesting verbose notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)| -|7|[rescanprogress](#rescanprogress)|A rescan operation that is underway has made progress.|[rescan](#rescan)| -|8|[rescanfinished](#rescanfinished)|A rescan operation has completed.|[rescan](#rescan)| +|7|[rescanprogress](#rescanprogress)|*DEPRECATED, notifications not used by [rescanblocks](#rescanblocks)*
A rescan operation that is underway has made progress.|[rescan](#rescan)| +|8|[rescanfinished](#rescanfinished)|*DEPRECATED, notifications not used by [rescanblocks](#rescanblocks)*
A rescan operation has completed.|[rescan](#rescan)| |9|[relevanttxaccepted](#relevanttxaccepted)|A transaction matching the tx filter has been accepted into the mempool.|[loadtxfilter](#loadtxfilter)| |10|[filteredblockconnected](#filteredblockconnected)|Block connected to the main chain; contains any transactions that match the client's tx filter.|[notifyblocks](#notifyblocks), [loadtxfilter](#loadtxfilter)| |11|[filteredblockdisconnected](#filteredblockdisconnected)|Block disconnected from the main chain.|[notifyblocks](#notifyblocks), [loadtxfilter](#loadtxfilter)| @@ -969,7 +983,7 @@ The following is an overview of the JSON-RPC notifications used for Websocket co |Method|rescanprogress| |Request|[rescan](#rescan)| |Parameters|1. Hash (string) hash of the last processed block
2. Height (numeric) height of the last processed block
3. Time (numeric) UNIX time of the last processed block| -|Description|Notifies a client with the current progress at periodic intervals when a long-running [rescan](#rescan) is underway.| +|Description|*DEPRECATED, notifications not used by [rescanblocks](#rescanblocks)*
Notifies a client with the current progress at periodic intervals when a long-running [rescan](#rescan) is underway.| |Example|`{`
 `"jsonrpc": "1.0",`
 `"method": "rescanprogress",`
 `"params":`
  `[`
   `"0000000000000ea86b49e11843b2ad937ac89ae74a963c7edd36e0147079b89d",`
   `127213,`
   `1306533807`
  `],`
 `"id": null`
`}`| [Return to Overview](#NotificationOverview)
@@ -982,7 +996,7 @@ The following is an overview of the JSON-RPC notifications used for Websocket co |Method|rescanfinished| |Request|[rescan](#rescan)| |Parameters|1. Hash (string) hash of the last rescanned block
2. Height (numeric) height of the last rescanned block
3. Time (numeric) UNIX time of the last rescanned block | -|Description|Notifies a client that the [rescan](#rescan) has completed and no further notifications will be sent.| +|Description|*DEPRECATED, notifications not used by [rescanblocks](#rescanblocks)*
Notifies a client that the [rescan](#rescan) has completed and no further notifications will be sent.| |Example|`{`
 `"jsonrpc": "1.0",`
 `"method": "rescanfinished",`
 `"params":`
  `[`
   `"0000000000000ea86b49e11843b2ad937ac89ae74a963c7edd36e0147079b89d",`
   `127213,`
   `1306533807`
  `],`
 `"id": null`
`}`| [Return to Overview](#NotificationOverview)