github.com/decred/dcrlnd@v0.7.6/lnrpc/chainrpc/chainnotifier.proto (about)

     1  syntax = "proto3";
     2  
     3  package chainrpc;
     4  
     5  option go_package = "github.com/decred/dcrlnd/lnrpc/chainrpc";
     6  
     7  // ChainNotifier is a service that can be used to get information about the
     8  // chain backend by registering notifiers for chain events.
     9  service ChainNotifier {
    10      /*
    11      RegisterConfirmationsNtfn is a synchronous response-streaming RPC that
    12      registers an intent for a client to be notified once a confirmation request
    13      has reached its required number of confirmations on-chain.
    14  
    15      A client can specify whether the confirmation request should be for a
    16      particular transaction by its hash or for an output script by specifying a
    17      zero hash.
    18      */
    19      rpc RegisterConfirmationsNtfn (ConfRequest) returns (stream ConfEvent);
    20  
    21      /*
    22      RegisterSpendNtfn is a synchronous response-streaming RPC that registers an
    23      intent for a client to be notification once a spend request has been spent
    24      by a transaction that has confirmed on-chain.
    25  
    26      A client can specify whether the spend request should be for a particular
    27      outpoint  or for an output script by specifying a zero outpoint.
    28      */
    29      rpc RegisterSpendNtfn (SpendRequest) returns (stream SpendEvent);
    30  
    31      /*
    32      RegisterBlockEpochNtfn is a synchronous response-streaming RPC that
    33      registers an intent for a client to be notified of blocks in the chain. The
    34      stream will return a hash and height tuple of a block for each new/stale
    35      block in the chain. It is the client's responsibility to determine whether
    36      the tuple returned is for a new or stale block in the chain.
    37  
    38      A client can also request a historical backlog of blocks from a particular
    39      point. This allows clients to be idempotent by ensuring that they do not
    40      missing processing a single block within the chain.
    41      */
    42      rpc RegisterBlockEpochNtfn (BlockEpoch) returns (stream BlockEpoch);
    43  }
    44  
    45  message ConfRequest {
    46      /*
    47      The transaction hash for which we should request a confirmation notification
    48      for. If set to a hash of all zeros, then the confirmation notification will
    49      be requested for the script instead.
    50      */
    51      bytes txid = 1;
    52  
    53      /*
    54      An output script within a transaction with the hash above which will be used
    55      by light clients to match block filters. If the transaction hash is set to a
    56      hash of all zeros, then a confirmation notification will be requested for
    57      this script instead.
    58      */
    59      bytes script = 2;
    60  
    61      /*
    62      The number of desired confirmations the transaction/output script should
    63      reach before dispatching a confirmation notification.
    64      */
    65      uint32 num_confs = 3;
    66  
    67      /*
    68      The earliest height in the chain for which the transaction/output script
    69      could have been included in a block. This should in most cases be set to the
    70      broadcast height of the transaction/output script.
    71      */
    72      uint32 height_hint = 4;
    73  }
    74  
    75  message ConfDetails {
    76      // The raw bytes of the confirmed transaction.
    77      bytes raw_tx = 1;
    78  
    79      // The hash of the block in which the confirmed transaction was included in.
    80      bytes block_hash = 2;
    81  
    82      // The height of the block in which the confirmed transaction was included
    83      // in.
    84      uint32 block_height = 3;
    85  
    86      // The index of the confirmed transaction within the transaction.
    87      uint32 tx_index = 4;
    88  }
    89  
    90  message Reorg {
    91      // TODO(wilmer): need to know how the client will use this first.
    92  }
    93  
    94  message ConfEvent {
    95      oneof event {
    96          /*
    97          An event that includes the confirmation details of the request
    98          (txid/ouput script).
    99          */
   100          ConfDetails conf = 1;
   101  
   102          /*
   103          An event send when the transaction of the request is reorged out of the
   104          chain.
   105          */
   106          Reorg reorg = 2;
   107      }
   108  }
   109  
   110  message Outpoint {
   111      // The hash of the transaction.
   112      bytes hash = 1;
   113  
   114      // The index of the output within the transaction.
   115      uint32 index = 2;
   116  }
   117  
   118  message SpendRequest {
   119      /*
   120      The outpoint for which we should request a spend notification for. If set to
   121      a zero outpoint, then the spend notification will be requested for the
   122      script instead.
   123      */
   124      Outpoint outpoint = 1;
   125  
   126      /*
   127      The output script for the outpoint above. This will be used by light clients
   128      to match block filters. If the outpoint is set to a zero outpoint, then a
   129      spend notification will be requested for this script instead.
   130      */
   131      bytes script = 2;
   132  
   133      /*
   134      The earliest height in the chain for which the outpoint/output script could
   135      have been spent. This should in most cases be set to the broadcast height of
   136      the outpoint/output script.
   137      */
   138      uint32 height_hint = 3;
   139  
   140      // TODO(wilmer): extend to support num confs on spending tx.
   141  }
   142  
   143  message SpendDetails {
   144      // The outpoint was that spent.
   145      Outpoint spending_outpoint = 1;
   146  
   147      // The raw bytes of the spending transaction.
   148      bytes raw_spending_tx = 2;
   149  
   150      // The hash of the spending transaction.
   151      bytes spending_tx_hash = 3;
   152  
   153      // The input of the spending transaction that fulfilled the spend request.
   154      uint32 spending_input_index = 4;
   155  
   156      // The height at which the spending transaction was included in a block.
   157      uint32 spending_height = 5;
   158  }
   159  
   160  message SpendEvent {
   161      oneof event {
   162          /*
   163          An event that includes the details of the spending transaction of the
   164          request (outpoint/output script).
   165          */
   166          SpendDetails spend = 1;
   167  
   168          /*
   169          An event sent when the spending transaction of the request was
   170          reorged out of the chain.
   171          */
   172          Reorg reorg = 2;
   173      }
   174  }
   175  
   176  message BlockEpoch {
   177      // The hash of the block.
   178      bytes hash = 1;
   179  
   180      // The height of the block.
   181      uint32 height = 2;
   182  }