diff --git a/v2/proto/page.proto b/v2/proto/page.proto new file mode 100644 index 0000000..cb12e8d --- /dev/null +++ b/v2/proto/page.proto @@ -0,0 +1,72 @@ +// 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; + + // if this output is a stream claim in a + // channel, this is a pointer to an output + // representing that channel (should be + // available in Page.txs) + Output channel = 3; +} + +message Transaction { + // entire raw transaction + bytes tx = 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; +}