types/v2/proto/page.proto

// Page message can represent the results of
// paginated queries to a server which return
// transactions and outputs. This should be
// enough to cover just about every blockchain
// type in LBRY: claims, supports, payments, etc.
//
// Assembling Result Page
// 
// To prevent unnecessarily duplicating the same
// raw TX many times if the result is TXOs in
// the same transaction, the Page is split between
// a list of `txos` (pointers) and a list of `txs`
// (actual raw transactions). To assemble the page,
//
//  1) Loop over all `txs`, parsing them into a TX
//     object as desired and adding them into a
//     mapping keyed by "tx hash -> TX object". 
//
//  2) Create a new list to hold the page results.
//
//  3) Loop over all `txos` adding it along with the
//     TX retrieved from previously created TX mapping.
//     Optionally, lookup and include the channel `txo`
//     using the same process.
//
//  4) You should now have a list of TXOs with their
//     associated TX and for claims in a channel also
//     associated channel TXO and TX.
//
// If the Page object is used strictly to return a list
// of TXs then the `txos` attribute will be empty. The
// semantics of which field is being paginated (`txos` vs
// `txs`) is determined in context of the RPC API. An
// RPC method such as `get_transactions` is likely to
// be paginating the `txs` list.
//
syntax = "proto3";

package pb;

message Page {
  repeated Output txos = 1;
  repeated Transaction txs = 2;
  uint32 total = 3;
  uint32 offset = 4;
}

message Output {
  // pointer to an output in one of the Page.txs
  bytes tx_hash = 1;
  uint32 nout = 2;
  oneof meta {
    ClaimMeta claim = 3;
  }
}

message ClaimMeta {
  Output channel = 1;
  bool is_winning = 2;
  uint64 activation_height = 3;
  uint64 effective_amount = 4;
  uint64 trending_amount = 5;
}

message Transaction {
  // entire raw transaction
  bytes raw = 1;

  // height progression
  //   -1: in mempool but has unconfirmed inputs
  //    0: in mempool and all inputs confirmed
  // +num: confirmed in a specific block (height)
  int32 height = 2;

  // position in block from top, only if height > 0
  uint32 position = 3;
}