// Copyright (c) 2019-2020 The Zcash developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or https://www.opensource.org/licenses/mit-license.php .

syntax = "proto3";
package cash.z.wallet.sdk.rpc;
option go_package = ".;walletrpc";
option swift_prefix = "";
import "service.proto";

message DarksideMetaState {
    int32 saplingActivation = 1;
    string branchID = 2;
    string chainName = 3;
}

message DarksideBlock {
    string block = 1;
}

message DarksideBlocksURL {
    string url = 2;
}

// A single transaction that should appear to be mined at the given height.
message DarksideTx {
    int32 height = 1;
    string transaction = 2;
}

// This service implements the following rpc methods:
//     SetMetaState
//     SetBlocks
//     SetBlocksURL
//     SetTx
//     GetIncomingTransactions
//
service DarksideStreamer {
    // Set (some of) the values that should be returned by GetLightdInfo()
    rpc SetMetaState(DarksideMetaState) returns (Empty) {}

    // SetBlocks() replaces the specified range of blocks (gaps not allowed);
    // for example, you can set blocks 1000-1006, do some tests, then set blocks
    // 1003-1004. This preserves blocks 1000-1002, replaces blocks 1003-1004,
    // and removes blocks 1005-1006. This can be used to simulate a chain reorg.
    // Blocks are hex-encoded.
    rpc SetBlocks(stream DarksideBlock) returns (Empty) {}

    // This is the same as SetBlocks(), except the blocks are fetched
    // from the given URL. Blocks are one per line, hex-encoded (not JSON).
    // SetBlocksURL("file:testdata/darkside/init-blocks") is done at startup.
    rpc SetBlocksURL(DarksideBlocksURL) returns (Empty) {}

    // SetTx() allows the test coordinator to submit a list of transactions and
    // for each indicate in which block it should appear.
    // For example,
    //   tx1, block=1001
    //   tx2, block=1002
    //   tx3, block=1002
    // Then use Setblocks(1000-1005): block 1001 will include tx1 (plus
    // any transactions were part of that block to begin with); tx2 and tx3
    // will appear in block 1002. Blocks 1003-1005 will be returned as submitted.
    //
    // If you first set a range of blocks, then submit transactions within that
    // range, it's too late for them to be included in those blocks. If blocks
    // are resubmitted, then those transactions are included in those blocks.
    //
    // Calling GetTransaction() on tx1-3 will return those transactions, and
    // GetTransaction() will also return any transactions that were part of
    // the submitted blocks.
    //
    // Each call to SetTx() completely replaces the stored transaction set.
    rpc SetTx(stream DarksideTx) returns (Empty) {}

    // Calls to SendTransaction() are accepted and stored; this method returns
    // all transactions that were previously submitted. This enables the
    // following kind of test, for example:
    //   1. wallet submits a transaction
    //   2. Test coordinator retrives the transaction using this interface
    //   3. Test coordinator submits the transaction using SetTx()
    //   4. Darksidewalletd simulates the transaction appearing in a mined block
    //
    rpc GetIncomingTransactions(Empty) returns (stream RawTransaction) {}
}