2020-03-12 10:57:02 -07:00
|
|
|
// 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 .
|
|
|
|
|
2018-11-30 09:03:35 -08:00
|
|
|
syntax = "proto3";
|
2019-01-07 11:20:47 -08:00
|
|
|
package cash.z.wallet.sdk.rpc;
|
2020-04-24 14:46:45 -07:00
|
|
|
option go_package = ".;walletrpc";
|
2019-08-30 11:52:46 -07:00
|
|
|
option swift_prefix = "";
|
2018-11-30 10:00:07 -08:00
|
|
|
import "compact_formats.proto";
|
|
|
|
|
2018-11-30 09:03:35 -08:00
|
|
|
// A BlockID message contains identifiers to select a block: a height or a
|
2020-02-26 08:36:55 -08:00
|
|
|
// hash. Specification by hash is not implemented, but may be in the future.
|
2018-11-30 09:03:35 -08:00
|
|
|
message BlockID {
|
|
|
|
uint64 height = 1;
|
|
|
|
bytes hash = 2;
|
|
|
|
}
|
|
|
|
|
2020-02-26 08:36:55 -08:00
|
|
|
// BlockRange specifies a series of blocks from start to end inclusive.
|
|
|
|
// Both BlockIDs must be heights; specification by hash is not yet supported.
|
2018-11-30 09:03:35 -08:00
|
|
|
message BlockRange {
|
|
|
|
BlockID start = 1;
|
|
|
|
BlockID end = 2;
|
|
|
|
}
|
|
|
|
|
|
|
|
// A TxFilter contains the information needed to identify a particular
|
|
|
|
// transaction: either a block and an index, or a direct transaction hash.
|
2020-02-26 08:36:55 -08:00
|
|
|
// Currently, only specification by hash is supported.
|
2018-11-30 09:03:35 -08:00
|
|
|
message TxFilter {
|
2020-03-31 12:47:52 -07:00
|
|
|
BlockID block = 1; // block identifier, height or hash
|
|
|
|
uint64 index = 2; // index within the block
|
|
|
|
bytes hash = 3; // transaction ID (hash, txid)
|
2018-11-30 09:03:35 -08:00
|
|
|
}
|
|
|
|
|
2019-11-27 15:32:26 -08:00
|
|
|
// RawTransaction contains the complete transaction data. It also optionally includes
|
2020-03-31 12:47:52 -07:00
|
|
|
// the block height in which the transaction was included.
|
2018-11-30 10:00:07 -08:00
|
|
|
message RawTransaction {
|
2020-03-31 12:47:52 -07:00
|
|
|
bytes data = 1; // exact data returned by zcash 'getrawtransaction'
|
|
|
|
uint64 height = 2; // height that the transaction was mined (or -1)
|
2018-11-30 09:03:35 -08:00
|
|
|
}
|
|
|
|
|
2020-02-26 08:36:55 -08:00
|
|
|
// A SendResponse encodes an error code and a string. It is currently used
|
|
|
|
// only by SendTransaction(). If error code is zero, the operation was
|
|
|
|
// successful; if non-zero, it and the message specify the failure.
|
2018-11-30 09:03:35 -08:00
|
|
|
message SendResponse {
|
|
|
|
int32 errorCode = 1;
|
|
|
|
string errorMessage = 2;
|
|
|
|
}
|
|
|
|
|
2020-02-26 08:36:55 -08:00
|
|
|
// Chainspec is a placeholder to allow specification of a particular chain fork.
|
2018-11-30 09:03:35 -08:00
|
|
|
message ChainSpec {}
|
|
|
|
|
2020-02-26 08:36:55 -08:00
|
|
|
// Empty is for gRPCs that take no arguments, currently only GetLightdInfo.
|
2019-12-17 10:57:17 -08:00
|
|
|
message Empty {}
|
|
|
|
|
2020-03-11 13:56:23 -07:00
|
|
|
// LightdInfo returns various information about this lightwalletd instance
|
2020-02-26 08:36:55 -08:00
|
|
|
// and the state of the blockchain.
|
2019-12-17 10:57:17 -08:00
|
|
|
message LightdInfo {
|
|
|
|
string version = 1;
|
|
|
|
string vendor = 2;
|
2020-03-31 12:47:52 -07:00
|
|
|
bool taddrSupport = 3; // true
|
|
|
|
string chainName = 4; // either "main" or "test"
|
|
|
|
uint64 saplingActivationHeight = 5; // depends on mainnet or testnet
|
|
|
|
string consensusBranchId = 6; // protocol identifier, see consensus/upgrades.cpp
|
|
|
|
uint64 blockHeight = 7; // latest block on the best chain
|
2019-12-17 10:57:17 -08:00
|
|
|
}
|
|
|
|
|
2020-02-26 08:36:55 -08:00
|
|
|
// TransparentAddressBlockFilter restricts the results to the given address
|
|
|
|
// or block range.
|
2019-11-27 15:32:26 -08:00
|
|
|
message TransparentAddressBlockFilter {
|
2020-03-31 12:47:52 -07:00
|
|
|
string address = 1; // t-address
|
|
|
|
BlockRange range = 2; // start, end heights
|
2019-11-27 15:32:26 -08:00
|
|
|
}
|
|
|
|
|
2020-03-11 13:56:23 -07:00
|
|
|
// Duration is currently used only for testing, so that the Ping rpc
|
|
|
|
// can simulate a delay, to create many simultaneous connections. Units
|
|
|
|
// are microseconds.
|
|
|
|
message Duration {
|
|
|
|
int64 intervalUs = 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
// PingResponse is used to indicate concurrency, how many Ping rpcs
|
|
|
|
// are executing upon entry and upon exit (after the delay).
|
2020-03-31 12:47:52 -07:00
|
|
|
// This rpc is used for testing only.
|
2020-03-11 13:56:23 -07:00
|
|
|
message PingResponse {
|
|
|
|
int64 entry = 1;
|
|
|
|
int64 exit = 2;
|
|
|
|
}
|
|
|
|
|
2020-08-06 09:05:02 -07:00
|
|
|
message Address {
|
|
|
|
string address = 1;
|
|
|
|
}
|
2020-08-11 22:59:20 -07:00
|
|
|
message AddressList {
|
2020-08-12 12:58:27 -07:00
|
|
|
repeated string addresses = 1;
|
2020-08-11 22:59:20 -07:00
|
|
|
}
|
|
|
|
message Balance {
|
|
|
|
int64 valueZat = 1;
|
2020-08-06 09:05:02 -07:00
|
|
|
}
|
|
|
|
|
2020-09-10 12:50:14 -07:00
|
|
|
message Exclude {
|
|
|
|
repeated bytes txid = 1;
|
|
|
|
}
|
|
|
|
|
2018-11-30 09:03:35 -08:00
|
|
|
service CompactTxStreamer {
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return the height of the tip of the best chain
|
2018-11-30 09:03:35 -08:00
|
|
|
rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return the compact block corresponding to the given block identifier
|
2018-11-30 09:03:35 -08:00
|
|
|
rpc GetBlock(BlockID) returns (CompactBlock) {}
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return a list of consecutive compact blocks
|
2018-11-30 09:03:35 -08:00
|
|
|
rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
|
2019-11-27 15:32:26 -08:00
|
|
|
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return the requested full (not compact) transaction (as from zcashd)
|
2018-11-30 10:00:07 -08:00
|
|
|
rpc GetTransaction(TxFilter) returns (RawTransaction) {}
|
2020-03-31 12:47:52 -07:00
|
|
|
// Submit the given transaction to the zcash network
|
2018-11-30 09:03:35 -08:00
|
|
|
rpc SendTransaction(RawTransaction) returns (SendResponse) {}
|
2019-12-17 10:57:17 -08:00
|
|
|
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return the txids corresponding to the given t-address within the given block range
|
2020-08-12 12:58:27 -07:00
|
|
|
rpc GetTaddressTxids(TransparentAddressBlockFilter) returns (stream RawTransaction) {}
|
|
|
|
rpc GetTaddressBalance(AddressList) returns (Balance) {}
|
|
|
|
rpc GetTaddressBalanceStream(stream Address) returns (Balance) {}
|
2019-11-27 15:32:26 -08:00
|
|
|
|
2020-09-10 12:50:14 -07:00
|
|
|
// Return the compact transactions currently in the mempool; the results
|
|
|
|
// can be a few seconds out of date. If the Exclude list is empty, return
|
|
|
|
// all transactions; otherwise return all *except* those in the Exclude list
|
|
|
|
// (if any); this allows the client to avoid receiving transactions that it
|
|
|
|
// already has (from an earlier call to this rpc). The transaction IDs in the
|
|
|
|
// Exclude list can be shortened to any number of bytes to make the request
|
|
|
|
// more bandwidth-efficient; if two or more transactions in the mempool
|
|
|
|
// match a shortened txid, they are all sent (none is excluded). Transactions
|
|
|
|
// in the exclude list that don't exist in the mempool are ignored.
|
|
|
|
rpc GetMempoolTx(Exclude) returns (stream CompactTx) {}
|
|
|
|
|
2020-03-31 12:47:52 -07:00
|
|
|
// Return information about this lightwalletd instance and the blockchain
|
2019-12-17 10:57:17 -08:00
|
|
|
rpc GetLightdInfo(Empty) returns (LightdInfo) {}
|
2020-03-31 12:47:52 -07:00
|
|
|
// Testing-only
|
2020-03-11 13:56:23 -07:00
|
|
|
rpc Ping(Duration) returns (PingResponse) {}
|
2018-11-30 09:03:35 -08:00
|
|
|
}
|