probing/README.md

Lightning Network probing utilities

# Probing

Utility methods to assist in probing Lightning Network destinations

# Methods

## getSyntheticOutIgnores

Get a synthetic ignore list to simulate an outbound restriction

    {
      [ignore]: [{
        from_public_key: <From Public Key Hex String>
        [to_public_key]: <To Public Key Hex String>
      }]
      lnd: <Authenticated LND API Object>
      out: [<Out Through Public Key Hex String>]
    }

    @returns via cbk or Promise
    {
      ignore: [{
        from_public_key: <From Public Key Hex String>
        to_public_key: <From Public Key Hex String>
      }]
    }

## subscribeToFindMaxPayable

Subscribe to a probe to find the max routable amount along a route

    {
      cltv: <Final CLTV Delta Number>
      [delay]: <Attempt Delay Milliseconds Number>
      hops: [{
        channel: <Standard Format Channel Id String>
        public_key: <Forward to Public Key With Hex String>
      }]
      lnd: <Authenticated LND API Object>
      max: <Max Attempt Tokens Number>
      [request]: <BOLT 11 Payment Request String>
      [routes]: [[{
        base_fee_mtokens: <Base Routing Fee In Millitokens Number>
        channel: <Standard Format Channel Id String>
        cltv_delta: <CLTV Blocks Delta Number>
        fee_rate: <Fee Rate In Millitokens Per Million Number>
        public_key: <Public Key Hex String>
      }]]
    }

    @returns
    <Find Max Payable EventEmitter Object>

    @event 'error'
    <Error Array>

    @event 'evaluating'
    {
      tokens: <Evaluating Tokens Number>
    }

    @event 'failure'
    {}

    @event 'success'
    {
      maximum: <Maximum Routeable Tokens Number>
    }

## subscribeToMultiPathPay

Subscribe to a payment over multiple paths

    {
      [cltv_delta]: <Final CLTV Delta Number>
      destination: <Destination Public Key Hex String>
      id: <Payment Hash Hex String>
      lnd: <Authenticated LND API Object>
      [max_attempts]: <Maximum Routing Failure Retries Number>
      max_fee: <Maximum Total Fee Tokens>
      [max_timeout]: <Maximum Payment Expiration Height Number>
      mtokens: <Total Millitokens to Send String>
      paths: [{
        channels: [<Standard Format Channel Id String>]
        fee: <Fee Amount Tokens>
        fee_mtokens: <Fee Amount Millitokens String>
        liquidity: <Liquidity Total Tokens>
        relays: [<Relaying Node Public Key Hex String>]
      }]
      payment: <Payment Identifier Hex String>
      [routes]: [[{
        [base_fee_mtokens]: <Base Fee Millitokens String>
        [channel]: <Standard Format Channel Id String>
        [cltv_delta]: <Final CLTV Expiration Blocks Delta Number>
        [fee_rate]: <Fee Rate Millitokens Per Million Number>
        public_key: <Forward Edge Public Key Hex String>
      }]]
    }

    @throws
    <Error Object>

    @returns
    <EventEmitter Object>

    @event 'error'
    <Error Array>

    @event 'failure'
    {}

    @event 'paid'
    {
      secret: <Payment Secret Preimage Hex String>
    }

    @event 'path_success'
    {
      fee: <Fee Paid Tokens Number>
      fee_mtokens: <Fee Paid Millitokens String>
      hops: [{
        channel: <Standard Format Channel Id String>
        channel_capacity: <Hop Channel Capacity Tokens Number>
        fee_mtokens: <Hop Forward Fee Millitokens String>
        forward_mtokens: <Hop Forwarded Millitokens String>
        timeout: <Hop CLTV Expiry Block Height Number>
      }]
      id: <Payment Hash Hex String>
      is_confirmed: <Is Confirmed Bool>
      is_outgoing: <Is Outoing Bool>
      mtokens: <Total Millitokens Sent String>
      route: {
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        mtokens: <Total Millitokens To Pay String>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
      }
      safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
      safe_tokens: <Payment Tokens Rounded Up Number>
      secret: <Payment Secret Preimage Hex String>
      tokens: <Total Tokens Sent Number>
    }

    @event 'paying'
    {
      route: {
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        mtokens: <Total Millitokens To Pay String>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
      }
    }

    @event 'routing_failure'
    {
      [channel]: <Standard Format Channel Id String>
      [height]: <Failure Height Context Number>
      [index]: <Failure Hop Index Number>
      [mtokens]: <Failure Related Millitokens String>
      [policy]: {
        base_fee_mtokens: <Base Fee Millitokens String>
        cltv_delta: <Locktime Delta Number>
        fee_rate: <Fees Charged in Millitokens Per Million Number>
        [is_disabled]: <Channel is Disabled Bool>
        max_htlc_mtokens: <Maximum HLTC Millitokens value String>
        min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
      }
      public_key: <Public Key Hex String>
      reason: <Failure Reason String>
      route: {
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        mtokens: <Total Millitokens To Pay String>
        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
        safe_tokens: <Payment Tokens Rounded Up Number>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
      }
      [timeout_height]: <Failure Related CLTV Timeout Height Number>
      [update]: {
        chain: <Chain Id Hex String>
        channel_flags: <Channel Flags Number>
        extra_opaque_data: <Extra Opaque Data Hex String>
        message_flags: <Message Flags Number>
        signature: <Channel Update Signature Hex String>
      }
    }

    @event 'success'
    {
      routes: [{
        fee: <Fee Paid Tokens Number>
        fee_mtokens: <Fee Paid Millitokens String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Hop Channel Capacity Tokens Number>
          fee_mtokens: <Hop Forward Fee Millitokens String>
          forward_mtokens: <Hop Forwarded Millitokens String>
          timeout: <Hop CLTV Expiry Block Height Number>
        }]
        id: <Payment Hash Hex String>
        is_confirmed: <Is Confirmed Bool>
        is_outgoing: <Is Outoing Bool>
        mtokens: <Total Millitokens Sent String>
        route: {
          fee: <Total Fee Tokens To Pay Number>
          fee_mtokens: <Total Fee Millitokens To Pay String>
          hops: [{
            channel: <Standard Format Channel Id String>
            channel_capacity: <Channel Capacity Tokens Number>
            fee: <Fee Number>
            fee_mtokens: <Fee Millitokens String>
            forward: <Forward Tokens Number>
            forward_mtokens: <Forward Millitokens String>
            public_key: <Public Key Hex String>
            timeout: <Timeout Block Height Number>
          }]
          mtokens: <Total Millitokens To Pay String>
          timeout: <Expiration Block Height Number>
          tokens: <Total Tokens To Pay Number>
        }
        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
        safe_tokens: <Payment Tokens Rounded Up Number>
        secret: <Payment Secret Preimage Hex String>
        tokens: <Total Tokens Sent Number>
      }]
    }

## subscribeToMultiPathProbe

Subscribe to find multiple paths to a destination

This method is not supported on versions below LND 0.10.0

    {
      [allow_stacking]: [{
        from_public_key: <Allow Path Stacking From Public Key Hex String>
        to_public_key: <Allow Path Stacking To Public Key Hex String>
      }]
      cltv_delta: <Final CLTV Delta Number>
      [destination]: <Destination Public Key Hex String>
      [features]: [{
        bit: <Feature Bit Number>
      }]
      [ignore]: [{
        from_public_key: <Avoid Node With Public Key Hex String>
        [to_public_key]: <To Public Key Hex String>
      }]
      [incoming_peer]: <Pay In Through Public Key Hex String>
      lnd: <Authenticated LND API Object>
      [max_paths]: <Maximum Probe Paths Number>
      [max_timeout_height]: <Maximum CLTV Timeout Height Number>
      [mtokens]: <Smallest Path Liquidity Millitokens Number>
      [outgoing_channel]: <Out Through Channel Id String>
      [path_timeout_ms]: <Skip Individual Path Attempt After Milliseconds Number>
      [probe_timeout_ms]: <Fail Individual Probe After Milliseconds Number>
      [routes]: [[{
        [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
        [channel]: <Standard Format Channel Id String>
        [cltv_delta]: <CLTV Blocks Delta Number>
        [fee_rate]: <Fee Rate In Millitokens Per Million Number>
        public_key: <Forward Edge Public Key Hex String>
      }]]
    }

    @throws
    <Error Array>

    @returns
    <EventEmitter Object>

    @event 'error'
    <Error Array>

    @event 'evaluating'
    {
      tokens: <Tokens Number>
    }

    @event 'failure'
    {}

    @event 'probing'
    {
      route: {
        [confidence]: <Route Confidence Score Out Of One Million Number>
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        [messages]: [{
          type: <Message Type Number String>
          value: <Message Raw Value Hex Encoded String>
        }]
        mtokens: <Total Millitokens To Pay String>
        [payment]: <Payment Identifier Hex String>
        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
        safe_tokens: <Payment Sent Tokens Rounded Up Number>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
        [total_mtokens]: <Total Millitokens String>
      }
    }

    @event 'routing_failure'
    {
      [channel]: <Standard Format Channel Id String>
      index: <Failure Index Number>
      [mtokens]: <Millitokens String>
      [policy]: {
        base_fee_mtokens: <Base Fee Millitokens String>
        cltv_delta: <Locktime Delta Number>
        fee_rate: <Fees Charged in Millitokens Per Million Number>
        [is_disabled]: <Channel is Disabled Bool>
        max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
        min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
        [public_key]: <Public Key Hex String>
        [updated_at]: <Updated At ISO 8601 Date String>
      }
      [public_key]: <Public Key Hex String>
      reason: <Failure Reason String>
      route: {
        [confidence]: <Route Confidence Score Out Of One Million Number>
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        [messages]: [{
          type: <Message Type Number String>
          value: <Message Raw Value Hex Encoded String>
        }]
        mtokens: <Total Millitokens To Pay String>
        [payment]: <Payment Identifier Hex String>
        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
        safe_tokens: <Payment Sent Tokens Rounded Up Number>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
        [total_mtokens]: <Total Millitokens String>
      }
      [update]: {
        chain: <Chain Id Hex String>
        channel_flags: <Channel Flags Number>
        extra_opaque_data: <Extra Opaque Data Hex String>
        message_flags: <Message Flags Number>
        signature: <Channel Update Signature Hex String>
      }
    }

    @event 'routing_success'
    {
      route: {
        [confidence]: <Route Confidence Score Out Of One Million Number>
        fee: <Total Fee Tokens To Pay Number>
        fee_mtokens: <Total Fee Millitokens To Pay String>
        hops: [{
          channel: <Standard Format Channel Id String>
          channel_capacity: <Channel Capacity Tokens Number>
          fee: <Fee Number>
          fee_mtokens: <Fee Millitokens String>
          forward: <Forward Tokens Number>
          forward_mtokens: <Forward Millitokens String>
          public_key: <Public Key Hex String>
          timeout: <Timeout Block Height Number>
        }]
        [messages]: [{
          type: <Message Type Number String>
          value: <Message Raw Value Hex Encoded String>
        }]
        mtokens: <Total Millitokens To Pay String>
        [payment]: <Payment Identifier Hex String>
        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
        safe_tokens: <Payment Sent Tokens Rounded Up Number>
        timeout: <Expiration Block Height Number>
        tokens: <Total Tokens To Pay Number>
        [total_mtokens]: <Total Millitokens String>
      }
      [update]: {
        chain: <Chain Id Hex String>
        channel_flags: <Channel Flags Number>
        extra_opaque_data: <Extra Opaque Data Hex String>
        message_flags: <Message Flags Number>
        signature: <Channel Update Signature Hex String>
      }
    }

    @event 'success'
    {
      paths: [{
        channels: [<Standard Format Channel Id String>]
        fee: <Fee Amount Tokens>
        fee_mtokens: <Fee Amount Millitokens String>
        liquidity: <Liquidity Total Tokens>
        relays: [<Relaying Node Public Key Hex String>]
      }]
    }