Wondering what’s next for npm?Check out our public roadmap! »

    bsv-coinselect

    4.2.5 • Public • Published

    bsv-coinselect

    An unspent transaction output (UTXO) selection module for Bitcoin SV. https://matterpool.io Originally forked from https://github.com/bitcoinjs/coinselect

    Problem and Overview

    Working with Unspent transaction outputs (UTXO) the developer must choose which "coins" to use for creating transactions. For instance, the developer may want to use the minimal number of UTXOs to pay all outputs at a given fee rate.

    This library makes it easy to select UTXO's according different policies.

    This is a client-side library only and can be used in any Javascript project. If you need to fetch UTXO's or broadcast BSV transactions then use the Filepay library at http://github.com/mattercloud/filepay which makes use of bsv-coinselect

    NOTE: Force a UTXO to be selected by specifying required: true

     
    const utxos = [
      {
        "address": "1CgPDEav5fdzry3V7tGADY4rHqG8oi4kfv",
        "txid": "a939afcb78a06239f02eefbfaabc6e0a78dfe3cd64f9676932cc1195796fa42f",
        "vout": 1,
        "value": 1000,
        "height": 617496,
        "confirmations": 18639,
        "scriptPubKey": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "script": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "outputIndex": 1,
        "required": true // Optional. If set, then forces use of this utxo
      },
      {
        "address": "1CgPDEav5fdzry3V7tGADY4rHqG8oi4kfv",
        "txid": "716e6b12d111984818d8c5e6d68446a52746d480d397d077cad598d55f059a65",
        "vout": 1,
        "value": 5000,
        "height": 616468,
        "confirmations": 19667,
        "scriptPubKey": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "script": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "outputIndex": 1
      },
      {
        "address": "1CgPDEav5fdzry3V7tGADY4rHqG8oi4kfv",
        "txid": "98e0987b5b5783ae083814f448f1dda52c18c881beda649c36576d0c81ee31f9",
        "vout": 1,
        "value": 10004,
        "height": 610466,
        "confirmations": 25669,
        "scriptPubKey": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "script": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
        "outputIndex": 1
      }
    ];
     
    const outputs = [
      {
        script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
        value: 1000,
      },
      {
        script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
        value: 546,
      },
      {
        script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
        value: 1000,
      },
      {
        script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
        value: 10000,
      },
    ];
    const changeScript = null; // Optional, set to arbitrary p2ph or script. Ex: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac'
    const { inputs, outputs, fee } = coinSelect(utxos, outputs, 0.5, null);
    // https://whatsonchain.com/tx/81576866d8c796540cfdb3f75d67d469e683fe506a0676eb2e9f9ee1876b7e1d

    Sample response:

    {
      fee: 232,
      inputs: [
        {
          "address": "1CgPDEav5fdzry3V7tGADY4rHqG8oi4kfv",
          "txid": "98e0987b5b5783ae083814f448f1dda52c18c881beda649c36576d0c81ee31f9",
          "vout": 1,
          "value": 10004,
          "height": 610466,
          "confirmations": 25669,
          "scriptPubKey": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
          "script": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
          "outputIndex": 1
        },
        {
          "address": "1CgPDEav5fdzry3V7tGADY4rHqG8oi4kfv",
          "txid": "716e6b12d111984818d8c5e6d68446a52746d480d397d077cad598d55f059a65",
          "vout": 1,
          "value": 5000,
          "height": 616468,
          "confirmations": 19667,
          "scriptPubKey": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
          "script": "76a914801c259a527abd83a977fd90a06b22d215fcad4988ac",
          "outputIndex": 1
        },
      ],
      "outputs": [
        {
          script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
          value: 1000,
        },
        {
          script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
          value: 546,
        },
        {
          script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
          value: 1000,
        },
        {
          script: '76a914801c259a527abd83a977fd90a06b22d215fcad4988ac',
          value: 10000,
        },
        {
          // This is the change script. Set to 'null', 'undefined', or valid script
          // or use bsv.Transaction.changeAddress() and setting this to undefined
          script: null,
          "value": 2226
        }
      ]
    };
     

    Algorithms

    Module Algorithm Re-orders UTXOs?
    require('coinselect') Accumulative - accumulates inputs until the target value (+fees) is reached, skipping
    require('coinselect/accumulative') Accumulative - accumulates inputs until the target value (+fees) is reached, skipping detrimental inputs -

    Note: Each algorithm will add a change output if the input - output - fee value difference is over a dust threshold. This is calculated independently by utils.finalize, irrespective of the algorithm chosen, for the purposes of safety.

    Example

    let coinSelect = require('coinselect')
    let feeRate = 55 // satoshis per byte
    let utxos = [
      ...,
      {
        txid: '...',
        vout: 0,
        ...,
        value: 10000,
      }
    ]
    let targets = [
      ...,
      {
        address: '1EHNa6Q4Jz2uvNExL497mE43ikXhwF6kZm',
        value: 5000
      },
      {
        script: '....',
        value: 5000
      }
    ]
     
    // ...
    let changeScript = null; // Generates a value, but leaves 'script' null.
    // Set changeScript to be the output script if you want it populated automatically
    let { inputs, outputs, fee } = coinSelect(utxos, targets, feeRate, changeScript, options)
     
    // the accumulated fee is always returned for analysis
    // Make sure to  set changeScript = undefined OR null OR a change script.
    console.log(fee)
     
    // .inputs and .outputs will be undefined if no solution was found
    if (!inputs || !outputs) return
     
    // Create a transaction with the selected inputs
    let tx = new bitcoin.Transaction().from(inputs);
    // Attach each output
    outputs.forEach(output => {
        const script = (new bitcoin.Script(output.script)).toString();
        tx.addOutput(new bitcoin.Transaction.Output({ script: script, satoshis: output.value }));
    })
    tx.change('address here');
    // Go on to tx.sign()... etc

    License MIT

    Install

    npm i bsv-coinselect

    DownloadsWeekly Downloads

    33

    Version

    4.2.5

    License

    MIT

    Unpacked Size

    14.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar
    • avatar