scantxoutset

scantxoutset "action" ( [scanobjects,...] )

EXPERIMENTAL WARNING: This function may be changed or removed in future versions.

Performs a scan on the unspent transaction output set for entries that match specified output descriptors.

Examples of output descriptors include:

addr(<address>) — Outputs where the scriptPubKey matches the given address (does not include P2PK).
raw(<hex script>) — Outputs where the scriptPubKey equals the provided hex script.
combo(<pubkey>) — P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH outputs for the specified pubkey.
pkh(<pubkey>) — P2PKH outputs for the given pubkey.
sh(multi(<n>,<pubkey>,<pubkey>,…)) — P2SH-multisig outputs for the specified threshold and pubkeys.

In these examples, <pubkey> can refer to a fixed public key in hexadecimal, or to an xpub/xprv followed by one or more path elements separated by “/”, and optionally ending in “/” (unhardened), “/’” or “/*h” (hardened) to include all child keys.

When using the latter, a range must be specified below if it differs from the default of 1000.

For more details on output descriptors, refer to the documentation in the doc/descriptors.md file.

Argument #1 – action

Type: string, required

The action to perform: "start" to initiate a scan. "abort" to stop the current scan (returns true if successfully aborted). "status" to report the current scan’s progress (in %).

Argument #2 – scanobjects

Type: json array

Array of scan objects. Required for “start” action: Every scan object is either a string descriptor or an object:

[
  "descriptor",             (string) An output descriptor
  {                         (json object) An object with output descriptor and metadata
    "desc": "str",          (string, required) An output descriptor
    "range": n or [n,n],    (numeric or array, optional, default=1000) The range of HD chain indexes to explore (either end or [begin,end])
  },
  ...
]

Result

{                                (json object)
  "success" : true|false,        (boolean) Whether the scan was completed
  "txouts" : n,                  (numeric) The number of unspent transaction outputs scanned
  "height" : n,                  (numeric) The current block height (index)
  "bestblock" : "hex",           (string) The hash of the block at the tip of the chain
  "unspents" : [                 (json array)
    {                            (json object)
      "txid" : "hex",            (string) The transaction id
      "vout" : n,                (numeric) The vout value
      "scriptPubKey" : "hex",    (string) The script key
      "desc" : "str",            (string) A specialized descriptor for the matched scriptPubKey
      "amount" : n,              (numeric) The total amount in BTCE of the unspent output
      "height" : n               (numeric) Height of the unspent transaction output
    },
    ...
  ],
  "total_amount" : n             (numeric) The total amount of all found unspent outputs in BTCE
}