From 1dbe4691a50b4a332775cd97ae40d714425f1152 Mon Sep 17 00:00:00 2001 From: Larry Ruane Date: Thu, 21 May 2020 11:25:53 -0600 Subject: [PATCH] darkside.proto doc improvements --- docs/rtd/index.html | 12 ++++++++---- walletrpc/darkside.pb.go | 22 ++++++++++++++++------ walletrpc/darkside.proto | 12 ++++++++---- 3 files changed, 32 insertions(+), 14 deletions(-) diff --git a/docs/rtd/index.html b/docs/rtd/index.html index 6bba5bf..dae36b3 100644 --- a/docs/rtd/index.html +++ b/docs/rtd/index.html @@ -710,7 +710,8 @@ staged blocks and transactions) and lightwalletd state (cache) to empty, the same as the initial state. This occurs synchronously and instantaneously; no reorg happens in lightwalletd. This is good to do before each independent test so that no state leaks from one test to another. -Also sets (some of) the values returned by GetLightdInfo().

+Also sets (some of) the values returned by GetLightdInfo(). The Sapling +activation height specified here must be where the block range starts.

@@ -719,7 +720,7 @@ Also sets (some of) the values returned by GetLightdInfo().

Empty

StageBlocksStream accepts a list of blocks and saves them into the blocks staging area until ApplyStaged() is called; there is no immediate effect on -the mock zcashd. Blocks are hex-encoded.

+the mock zcashd. Blocks are hex-encoded. Order is important, see ApplyStaged.

@@ -745,7 +746,7 @@ transactions) and same height, with two different hashes.

StageTransactionsStream RawTransaction stream Empty -

StageTransactions stores the given transaction-height pairs in the +

StageTransactionsStream stores the given transaction-height pairs in the staging area until ApplyStaged() is called. Note that these transactions are not returned by the production GetTransaction() gRPC until they appear in a "mined" block (contained in the active blockchain presented @@ -756,7 +757,10 @@ by the mock zcashd).

StageTransactions DarksideTransactionsURL Empty -

+

StageTransactions is the same except the transactions are fetched +from the given url. They are all staged into the block at the given +height. Staging transactions at multiple different heights requires +multiple calls.

diff --git a/walletrpc/darkside.pb.go b/walletrpc/darkside.pb.go index b0d6a0e..ea13a84 100644 --- a/walletrpc/darkside.pb.go +++ b/walletrpc/darkside.pb.go @@ -617,11 +617,12 @@ type DarksideStreamerClient interface { // the same as the initial state. This occurs synchronously and instantaneously; // no reorg happens in lightwalletd. This is good to do before each independent // test so that no state leaks from one test to another. - // Also sets (some of) the values returned by GetLightdInfo(). + // Also sets (some of) the values returned by GetLightdInfo(). The Sapling + // activation height specified here must be where the block range starts. Reset(ctx context.Context, in *DarksideMetaState, opts ...grpc.CallOption) (*Empty, error) // StageBlocksStream accepts a list of blocks and saves them into the blocks // staging area until ApplyStaged() is called; there is no immediate effect on - // the mock zcashd. Blocks are hex-encoded. + // the mock zcashd. Blocks are hex-encoded. Order is important, see ApplyStaged. StageBlocksStream(ctx context.Context, opts ...grpc.CallOption) (DarksideStreamer_StageBlocksStreamClient, error) // StageBlocks is the same as StageBlocksStream() except the blocks are fetched // from the given URL. Blocks are one per line, hex-encoded (not JSON). @@ -632,12 +633,16 @@ type DarksideStreamerClient interface { // lets you create two fake blocks with the same transactions (or no // transactions) and same height, with two different hashes. StageBlocksCreate(ctx context.Context, in *DarksideEmptyBlocks, opts ...grpc.CallOption) (*Empty, error) - // StageTransactions stores the given transaction-height pairs in the + // StageTransactionsStream stores the given transaction-height pairs in the // staging area until ApplyStaged() is called. Note that these transactions // are not returned by the production GetTransaction() gRPC until they // appear in a "mined" block (contained in the active blockchain presented // by the mock zcashd). StageTransactionsStream(ctx context.Context, opts ...grpc.CallOption) (DarksideStreamer_StageTransactionsStreamClient, error) + // StageTransactions is the same except the transactions are fetched + // from the given url. They are all staged into the block at the given + // height. Staging transactions at multiple different heights requires + // multiple calls. StageTransactions(ctx context.Context, in *DarksideTransactionsURL, opts ...grpc.CallOption) (*Empty, error) // ApplyStaged iterates the list of blocks that were staged by the // StageBlocks*() gRPCs, in the order they were staged, and "merges" each @@ -835,11 +840,12 @@ type DarksideStreamerServer interface { // the same as the initial state. This occurs synchronously and instantaneously; // no reorg happens in lightwalletd. This is good to do before each independent // test so that no state leaks from one test to another. - // Also sets (some of) the values returned by GetLightdInfo(). + // Also sets (some of) the values returned by GetLightdInfo(). The Sapling + // activation height specified here must be where the block range starts. Reset(context.Context, *DarksideMetaState) (*Empty, error) // StageBlocksStream accepts a list of blocks and saves them into the blocks // staging area until ApplyStaged() is called; there is no immediate effect on - // the mock zcashd. Blocks are hex-encoded. + // the mock zcashd. Blocks are hex-encoded. Order is important, see ApplyStaged. StageBlocksStream(DarksideStreamer_StageBlocksStreamServer) error // StageBlocks is the same as StageBlocksStream() except the blocks are fetched // from the given URL. Blocks are one per line, hex-encoded (not JSON). @@ -850,12 +856,16 @@ type DarksideStreamerServer interface { // lets you create two fake blocks with the same transactions (or no // transactions) and same height, with two different hashes. StageBlocksCreate(context.Context, *DarksideEmptyBlocks) (*Empty, error) - // StageTransactions stores the given transaction-height pairs in the + // StageTransactionsStream stores the given transaction-height pairs in the // staging area until ApplyStaged() is called. Note that these transactions // are not returned by the production GetTransaction() gRPC until they // appear in a "mined" block (contained in the active blockchain presented // by the mock zcashd). StageTransactionsStream(DarksideStreamer_StageTransactionsStreamServer) error + // StageTransactions is the same except the transactions are fetched + // from the given url. They are all staged into the block at the given + // height. Staging transactions at multiple different heights requires + // multiple calls. StageTransactions(context.Context, *DarksideTransactionsURL) (*Empty, error) // ApplyStaged iterates the list of blocks that were staged by the // StageBlocks*() gRPCs, in the order they were staged, and "merges" each diff --git a/walletrpc/darkside.proto b/walletrpc/darkside.proto index 8ba56ed..51cf9fb 100644 --- a/walletrpc/darkside.proto +++ b/walletrpc/darkside.proto @@ -53,12 +53,13 @@ service DarksideStreamer { // the same as the initial state. This occurs synchronously and instantaneously; // no reorg happens in lightwalletd. This is good to do before each independent // test so that no state leaks from one test to another. - // Also sets (some of) the values returned by GetLightdInfo(). + // Also sets (some of) the values returned by GetLightdInfo(). The Sapling + // activation height specified here must be where the block range starts. rpc Reset(DarksideMetaState) returns (Empty) {} // StageBlocksStream accepts a list of blocks and saves them into the blocks // staging area until ApplyStaged() is called; there is no immediate effect on - // the mock zcashd. Blocks are hex-encoded. + // the mock zcashd. Blocks are hex-encoded. Order is important, see ApplyStaged. rpc StageBlocksStream(stream DarksideBlock) returns (Empty) {} // StageBlocks is the same as StageBlocksStream() except the blocks are fetched @@ -72,16 +73,19 @@ service DarksideStreamer { // transactions) and same height, with two different hashes. rpc StageBlocksCreate(DarksideEmptyBlocks) returns (Empty) {} - // StageTransactions stores the given transaction-height pairs in the + // StageTransactionsStream stores the given transaction-height pairs in the // staging area until ApplyStaged() is called. Note that these transactions // are not returned by the production GetTransaction() gRPC until they // appear in a "mined" block (contained in the active blockchain presented // by the mock zcashd). rpc StageTransactionsStream(stream RawTransaction) returns (Empty) {} + // StageTransactions is the same except the transactions are fetched + // from the given url. They are all staged into the block at the given + // height. Staging transactions at multiple different heights requires + // multiple calls. rpc StageTransactions(DarksideTransactionsURL) returns (Empty) {} - // ApplyStaged iterates the list of blocks that were staged by the // StageBlocks*() gRPCs, in the order they were staged, and "merges" each // into the active, working blocks list that the mock zcashd is presenting