212 lines
8.6 KiB
Protocol Buffer
212 lines
8.6 KiB
Protocol Buffer
// 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 = "lightwalletd/walletrpc";
|
|
option swift_prefix = "";
|
|
import "compact_formats.proto";
|
|
|
|
// A BlockID message contains identifiers to select a block: a height or a
|
|
// hash. Specification by hash is not implemented, but may be in the future.
|
|
message BlockID {
|
|
uint64 height = 1;
|
|
bytes hash = 2;
|
|
}
|
|
|
|
// BlockRange specifies a series of blocks from start to end inclusive.
|
|
// Both BlockIDs must be heights; specification by hash is not yet supported.
|
|
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.
|
|
// Currently, only specification by hash is supported.
|
|
message TxFilter {
|
|
BlockID block = 1; // block identifier, height or hash
|
|
uint64 index = 2; // index within the block
|
|
bytes hash = 3; // transaction ID (hash, txid)
|
|
}
|
|
|
|
// RawTransaction contains the complete transaction data. It also optionally includes
|
|
// the block height in which the transaction was included, or, when returned
|
|
// by GetMempoolStream(), the latest block height.
|
|
message RawTransaction {
|
|
bytes data = 1; // exact data returned by Zcash 'getrawtransaction'
|
|
uint64 height = 2; // height that the transaction was mined (or -1)
|
|
}
|
|
|
|
// 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.
|
|
message SendResponse {
|
|
int32 errorCode = 1;
|
|
string errorMessage = 2;
|
|
}
|
|
|
|
// Chainspec is a placeholder to allow specification of a particular chain fork.
|
|
message ChainSpec {}
|
|
|
|
// Empty is for gRPCs that take no arguments, currently only GetLightdInfo.
|
|
message Empty {}
|
|
|
|
// LightdInfo returns various information about this lightwalletd instance
|
|
// and the state of the blockchain.
|
|
message LightdInfo {
|
|
string version = 1;
|
|
string vendor = 2;
|
|
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
|
|
string gitCommit = 8;
|
|
string branch = 9;
|
|
string buildDate = 10;
|
|
string buildUser = 11;
|
|
uint64 estimatedHeight = 12; // less than tip height if zcashd is syncing
|
|
string zcashdBuild = 13; // example: "v4.1.1-877212414"
|
|
string zcashdSubversion = 14; // example: "/MagicBean:4.1.1/"
|
|
}
|
|
|
|
// TransparentAddressBlockFilter restricts the results to the given address
|
|
// or block range.
|
|
message TransparentAddressBlockFilter {
|
|
string address = 1; // t-address
|
|
BlockRange range = 2; // start, end heights
|
|
}
|
|
|
|
// 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).
|
|
// This rpc is used for testing only.
|
|
message PingResponse {
|
|
int64 entry = 1;
|
|
int64 exit = 2;
|
|
}
|
|
|
|
message Address {
|
|
string address = 1;
|
|
}
|
|
message AddressList {
|
|
repeated string addresses = 1;
|
|
}
|
|
message Balance {
|
|
int64 valueZat = 1;
|
|
}
|
|
|
|
message Exclude {
|
|
repeated bytes txid = 1;
|
|
}
|
|
|
|
// The TreeState is derived from the Zcash z_gettreestate rpc.
|
|
message TreeState {
|
|
string network = 1; // "main" or "test"
|
|
uint64 height = 2; // block height
|
|
string hash = 3; // block id
|
|
uint32 time = 4; // Unix epoch time when the block was mined
|
|
string saplingTree = 5; // sapling commitment tree state
|
|
string orchardTree = 6; // orchard commitment tree state
|
|
}
|
|
|
|
enum ShieldedProtocol {
|
|
sapling = 0;
|
|
orchard = 1;
|
|
}
|
|
|
|
message GetSubtreeRootsArg {
|
|
uint32 startIndex = 1; // Index identifying where to start returning subtree roots
|
|
ShieldedProtocol shieldedProtocol = 2; // Shielded protocol to return subtree roots for
|
|
uint32 maxEntries = 3; // Maximum number of entries to return, or 0 for all entries.
|
|
}
|
|
message SubtreeRoot {
|
|
bytes rootHash = 2; // The 32-byte Merkle root of the subtree.
|
|
bytes completingBlockHash = 3; // The hash of the block that completed this subtree.
|
|
uint64 completingBlockHeight = 4; // The height of the block that completed this subtree in the main chain.
|
|
}
|
|
|
|
// Results are sorted by height, which makes it easy to issue another
|
|
// request that picks up from where the previous left off.
|
|
message GetAddressUtxosArg {
|
|
repeated string addresses = 1;
|
|
uint64 startHeight = 2;
|
|
uint32 maxEntries = 3; // zero means unlimited
|
|
}
|
|
message GetAddressUtxosReply {
|
|
string address = 6;
|
|
bytes txid = 1;
|
|
int32 index = 2;
|
|
bytes script = 3;
|
|
int64 valueZat = 4;
|
|
uint64 height = 5;
|
|
}
|
|
message GetAddressUtxosReplyList {
|
|
repeated GetAddressUtxosReply addressUtxos = 1;
|
|
}
|
|
|
|
service CompactTxStreamer {
|
|
// Return the height of the tip of the best chain
|
|
rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
|
|
// Return the compact block corresponding to the given block identifier
|
|
rpc GetBlock(BlockID) returns (CompactBlock) {}
|
|
// Same as GetBlock except actions contain only nullifiers
|
|
rpc GetBlockNullifiers(BlockID) returns (CompactBlock) {}
|
|
// Return a list of consecutive compact blocks
|
|
rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
|
|
// Same as GetBlockRange except actions contain only nullifiers
|
|
rpc GetBlockRangeNullifiers(BlockRange) returns (stream CompactBlock) {}
|
|
|
|
// Return the requested full (not compact) transaction (as from zcashd)
|
|
rpc GetTransaction(TxFilter) returns (RawTransaction) {}
|
|
// Submit the given transaction to the Zcash network
|
|
rpc SendTransaction(RawTransaction) returns (SendResponse) {}
|
|
|
|
// Return the txids corresponding to the given t-address within the given block range
|
|
rpc GetTaddressTxids(TransparentAddressBlockFilter) returns (stream RawTransaction) {}
|
|
rpc GetTaddressBalance(AddressList) returns (Balance) {}
|
|
rpc GetTaddressBalanceStream(stream Address) returns (Balance) {}
|
|
|
|
// 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) {}
|
|
|
|
// Return a stream of current Mempool transactions. This will keep the output stream open while
|
|
// there are mempool transactions. It will close the returned stream when a new block is mined.
|
|
rpc GetMempoolStream(Empty) returns (stream RawTransaction) {}
|
|
|
|
// GetTreeState returns the note commitment tree state corresponding to the given block.
|
|
// See section 3.7 of the Zcash protocol specification. It returns several other useful
|
|
// values also (even though they can be obtained using GetBlock).
|
|
// The block can be specified by either height or hash.
|
|
rpc GetTreeState(BlockID) returns (TreeState) {}
|
|
rpc GetLatestTreeState(Empty) returns (TreeState) {}
|
|
|
|
// Returns a stream of information about roots of subtrees of the Sapling and Orchard
|
|
// note commitment trees.
|
|
rpc GetSubtreeRoots(GetSubtreeRootsArg) returns (stream SubtreeRoot) {}
|
|
|
|
rpc GetAddressUtxos(GetAddressUtxosArg) returns (GetAddressUtxosReplyList) {}
|
|
rpc GetAddressUtxosStream(GetAddressUtxosArg) returns (stream GetAddressUtxosReply) {}
|
|
|
|
// Return information about this lightwalletd instance and the blockchain
|
|
rpc GetLightdInfo(Empty) returns (LightdInfo) {}
|
|
// Testing-only, requires lightwalletd --ping-very-insecure (do not enable in production)
|
|
rpc Ping(Duration) returns (PingResponse) {}
|
|
}
|