Protocol files
The wallet API is defined by the
LightWallet Protocol .proto files and their
CHANGELOG. There is no ZIP for it. Zingod implements one protocol release and reports it in
GetLightdInfo.lightwalletProtocolVersion.
The files below are the ones Zingod builds from. They differ from upstream in service.proto:
PingandGetBlockNullifiersare removed, and returnUNIMPLEMENTED.GetBlockRangeNullifiersandGetTaddressTxidsare marked deprecated.
service.proto
// 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";
// An identifier for a Zcash value pool.
enum PoolType {
POOL_TYPE_INVALID = 0;
TRANSPARENT = 1;
SAPLING = 2;
ORCHARD = 3;
IRONWOOD = 4;
}
// A BlockID message contains identifiers to select a block: a height or a
// hash. Support for specification by hash is not mandatory. (If `hash` is
// non-empty, the rpc may return an error.) This field is present to support
// a possible future upgrade.
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.
//
// If no pool types are specified, the server should default to the legacy
// behavior of returning only data relevant to the shielded (Sapling, Orchard,
// and Ironwood) pools; otherwise, the server should prune `CompactBlock`s
// returned to include only data relevant to the requested pool types. Clients MUST
// verify that the version of the server they are connected to are capable
// of returning pruned and/or transparent data before setting `poolTypes`
// to a non-empty value.
message BlockRange {
BlockID start = 1;
BlockID end = 2;
repeated PoolType poolTypes = 3;
}
// 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.
//
// FIXME: the documentation here about mempool status contradicts the documentation
// for the `height` field. See https://github.com/zcash/librustzcash/issues/1484
message RawTransaction {
// The serialized representation of the Zcash transaction.
bytes data = 1;
// The height at which the transaction is mined, or a sentinel value.
//
// Due to an error in the original protobuf definition, it is necessary to
// reinterpret the result of the `getrawtransaction` RPC call. Zcashd will
// return the int64 value `-1` for the height of transactions that appear
// in the block index, but which are not mined in the main chain. Here, the
// height field of `RawTransaction` was erroneously created as a `uint64`,
// and as such we must map the response from the zcashd RPC API to be
// representable within this space. Additionally, the `height` field will
// be absent for transactions in the mempool, resulting in the default
// value of `0` being set. Therefore, the meanings of the `height` field of
// the `RawTransaction` type are as follows:
//
// * height 0: the transaction is in the mempool
// * height 0xffffffffffffffff: the transaction has been mined on a fork that
// is not currently the main chain
// * any other height: the transaction has been mined in the main chain at the
// given height
uint64 height = 2;
}
// 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/"
string donationAddress = 15; // Zcash donation UA address
string upgradeName = 16; // name of next pending network upgrade, empty if none scheduled
uint64 upgradeHeight = 17; // height of next pending upgrade, zero if none is scheduled
string lightwalletProtocolVersion = 18; // version of https://github.com/zcash/lightwallet-protocol served by this server
}
// TransparentAddressBlockFilter restricts the results of the GRPC methods that
// use it to the transactions that involve the given address and were mined in
// the specified block range. Non-default values for both the address and the
// block range must be specified. Mempool transactions are not included.
//
// The `poolTypes` field of the `range` argument should be ignored.
// Implementations MAY consider it an error if any pool types are specified.
message TransparentAddressBlockFilter {
string address = 1; // t-address
BlockRange range = 2; // start, end heights only
}
message Address {
string address = 1;
}
message AddressList {
repeated string addresses = 1;
}
message Balance {
int64 valueZat = 1;
}
// Request parameters for the `GetMempoolTx` RPC.
message GetMempoolTxRequest {
// A list of transaction ID byte string suffixes that should be excluded
// from the response. These suffixes may be produced either directly from
// the underlying txid bytes, or, if the source values are encoded txid
// strings, by truncating the hexadecimal representation of each
// transaction ID to an even number of characters, and then hex-decoding
// and then byte-reversing this value to obtain the byte representation.
repeated bytes exclude_txid_suffixes = 1;
// We reserve field number 2 for a potential future `exclude_txid_prefixes`
// field.
reserved 2;
// The server must prune `CompactTx`s returned to include only data
// relevant to the requested pool types. If no pool types are specified,
// the server should default to the legacy behavior of returning only data
// relevant to the shielded (Sapling, Orchard, and Ironwood) pools.
repeated PoolType poolTypes = 3;
}
// 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
string ironwoodTree = 7; // ironwood commitment tree state
}
enum ShieldedProtocol {
sapling = 0;
orchard = 1;
ironwood = 2;
}
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;
}
// StandardFee is the reply to the GetStandardFee rpc: the ZIP 317
// marginal fee, in zatoshis per logical action, that wallets should
// pay for a transaction to be mined in the next block, as reported by
// the backend's `getstandardfee` RPC.
message StandardFee {
uint64 feeZat = 1; // standard fee in zatoshis per logical action
uint32 estimatorVersion = 2; // backend fee-estimator version, 0 = static ZIP 317 marginal fee
}
service CompactTxStreamer {
// Return the BlockID of the block at the tip of the best chain
rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
// Return the compact block corresponding to the given block identifier.
//
// The returned `CompactBlock` includes transaction data for all value
// pools, including transparent inputs (`vin`) and outputs (`vout`). This
// differs from `GetBlockRange`, which supports filtering by pool type and
// defaults to returning only shielded (Sapling, Orchard, and Ironwood)
// data. Clients that require only data for specific pools should use
// `GetBlockRange` with the appropriate `poolTypes` set.
//
// Note: the single null-outpoint input for coinbase transactions is
// omitted from the `vin` field of the corresponding `CompactTx`. See the
// documentation of the `CompactTx` message for details.
rpc GetBlock(BlockID) returns (CompactBlock) {}
// Return a list of consecutive compact blocks in the specified range,
// which is inclusive of `range.end`.
//
// If range.start <= range.end, blocks are returned increasing height order;
// otherwise blocks are returned in decreasing height order.
rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
// !!! TODO: REMOVE THIS. DEPRECATED. Served by Zingod only because pepper-sync still calls it;
// !!! delete once pepper-sync requests `GetBlockRange` with `poolTypes` instead.
//
// Return a stream of compact blocks for the specified range, where each
// block contains only nullifier information for the shielded pools
// (Sapling spend nullifiers, Orchard action nullifiers, and Ironwood action
// nullifiers). Transparent transaction data, Sapling outputs, full
// Orchard/Ironwood action data, and commitment tree sizes are not included.
// Implementations MUST ignore any
// `PoolType::TRANSPARENT` member of the `poolTypes` field of the request.
//
// Note: this method is deprecated; use `GetBlockRange` with the
// appropriate `poolTypes` instead.
rpc GetBlockRangeNullifiers(BlockRange) returns (stream CompactBlock) {
option deprecated = true;
}
// 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) {}
// !!! TODO: REMOVE THIS. DEPRECATED. Served by Zingod only because pepper-sync still calls it;
// !!! delete once pepper-sync calls `GetTaddressTransactions` (same request, same response).
//
// Return RawTransactions that match the given transparent address filter.
//
// Note: This function is misnamed, it returns complete `RawTransaction` values, not TxIds.
// NOTE: this method is deprecated, please use GetTaddressTransactions instead.
rpc GetTaddressTxids(TransparentAddressBlockFilter) returns (stream RawTransaction) {
option deprecated = true;
}
// Return the transactions corresponding to the given t-address within the given block range.
// Mempool transactions are not included in the results.
rpc GetTaddressTransactions(TransparentAddressBlockFilter) returns (stream RawTransaction) {}
rpc GetTaddressBalance(AddressList) returns (Balance) {}
rpc GetTaddressBalanceStream(stream Address) returns (Balance) {}
// Returns a stream of the compact transaction representation for transactions
// currently in the mempool. The results of this operation may be a few
// seconds out of date. If the `exclude_txid_suffixes` list is empty,
// return all transactions; otherwise return all *except* those in the
// `exclude_txid_suffixes` 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_txid_suffixes` 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
// txid suffix, none of the matching transactions are excluded. Txid
// suffixes in the exclude list that don't match any transactions in the
// mempool are ignored.
rpc GetMempoolTx(GetMempoolTxRequest) 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 note commitment tree
// for the specified shielded protocol (Sapling, Orchard, or Ironwood).
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) {}
// Return the standard fee (the ZIP 317 marginal fee, in zatoshis per
// logical action) that the backend recommends wallets pay for a
// transaction to be mined in the next block. Requires a backend that
// implements the `getstandardfee` RPC. Backends that lack it return
// Unimplemented.
rpc GetStandardFee(Empty) returns (StandardFee) {}
}
compact_formats.proto
// Copyright (c) 2019-2021 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 = "";
// REMINDER: proto3 fields are all optional. A field that is not present will be set to its zero/false/empty
// value.
// Information about the state of the chain as of a given block.
message ChainMetadata {
uint32 saplingCommitmentTreeSize = 1; // the size of the Sapling note commitment tree as of the end of this block
uint32 orchardCommitmentTreeSize = 2; // the size of the Orchard note commitment tree as of the end of this block
uint32 ironwoodCommitmentTreeSize = 3; // the size of the Ironwood note commitment tree as of the end of this block
}
// A compact representation of a Zcash block.
//
// CompactBlock is a packaging of ONLY the data from a block that's needed to:
// 1. Detect a payment to your Shielded address
// 2. Detect a spend of your Shielded notes
// 3. Update your witnesses to generate new spend proofs.
// 4. Spend UTXOs associated to t-addresses of your wallet.
//
// Currently, the `header` field should always be unset (empty). In the future,
// the presence or absence of header data may be made dependent on request
// parameters, although it is likely that such flexibility will only be provided via
// newly-added service methods, not via existing APIs.
message CompactBlock {
// Field 1 (`protoVersion`) was removed; see
// https://github.com/zcash/lightwallet-protocol/issues/25
reserved 1;
reserved "protoVersion";
uint64 height = 2; // the height of this block
bytes hash = 3; // if present, the ID (hash) of this block
bytes prevHash = 4; // if present, the ID (hash) of this block's predecessor
uint32 time = 5; // if non-zero, Unix epoch time when the block was mined
bytes header = 6; // if present, full header (as returned by the getblock RPC)
repeated CompactTx vtx = 7; // zero or more compact transactions from this block
ChainMetadata chainMetadata = 8; // information about the state of the chain as of this block
}
// A compact representation of a Zcash transaction.
//
// CompactTx contains the minimum information for a wallet to know if this transaction
// is relevant to it (either pays to it or spends from it) via shielded elements. Additionally,
// it can optionally include the minimum necessary data to detect payments to transparent addresses
// related to your wallet.
message CompactTx {
// The index of the transaction within the block.
uint64 index = 1;
// The id of the transaction as defined in
// [§ 7.1.1 ‘Transaction Identifiers’](https://zips.z.cash/protocol/protocol.pdf#txnidentifiers)
// This byte array MUST be in protocol order and MUST NOT be reversed
// or hex-encoded; the byte-reversed and hex-encoded representation is
// exclusively a textual representation of a txid.
bytes txid = 2;
// The transaction fee: present if server can provide. In the case of a
// stateless server and a transaction with transparent inputs, this will be
// unset because the calculation requires reference to prior transactions.
// If there are no transparent inputs, the fee will be calculable as:
// valueBalanceSapling + valueBalanceOrchard + valueBalanceIronwood
// + sum(vPubNew) - sum(vPubOld) - sum(tOut)
uint32 fee = 3;
repeated CompactSaplingSpend spends = 4;
repeated CompactSaplingOutput outputs = 5;
repeated CompactOrchardAction actions = 6;
repeated CompactOrchardAction ironwoodActions = 9;
// `CompactTxIn` values corresponding to the `vin` entries of the full transaction.
//
// Note: the single null-outpoint input for coinbase transactions is omitted. Light
// clients can test `CompactTx.index == 0` to determine whether a `CompactTx`
// represents a coinbase transaction, as the coinbase transaction is always the
// first transaction in any block.
repeated CompactTxIn vin = 7;
// A sequence of transparent outputs being created by the transaction.
repeated TxOut vout = 8;
}
// A compact representation of a transparent transaction input.
message CompactTxIn {
// The id of the transaction that generated the output being spent. This
// byte array must be in protocol order and MUST NOT be reversed or
// hex-encoded.
bytes prevoutTxid = 1;
// The index of the output being spent in the `vout` array of the
// transaction referred to by `prevoutTxid`.
uint32 prevoutIndex = 2;
}
// A transparent output being created by the transaction.
//
// This contains identical data to the `TxOut` type in the transaction itself, and
// thus it is not "compact".
message TxOut {
// The value of the output, in Zatoshis.
uint64 value = 1;
// The script pubkey that must be satisfied in order to spend this output.
bytes scriptPubKey = 2;
}
// A compact representation of a [Sapling Spend](https://zips.z.cash/protocol/protocol.pdf#spendencodingandconsensus).
//
// CompactSaplingSpend is a Sapling Spend Description as described in 7.3 of the Zcash
// protocol specification.
message CompactSaplingSpend {
bytes nf = 1; // Nullifier (see the Zcash protocol specification)
}
// A compact representation of a [Sapling Output](https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus).
//
// It encodes the `cmu` field, `ephemeralKey` field, and a 52-byte prefix of the
// `encCiphertext` field of a Sapling Output Description. Total size is 116 bytes.
message CompactSaplingOutput {
bytes cmu = 1; // Note commitment u-coordinate.
bytes ephemeralKey = 2; // Ephemeral public key.
bytes ciphertext = 3; // First 52 bytes of ciphertext.
}
// A compact representation of an [Orchard Action](https://zips.z.cash/protocol/protocol.pdf#actionencodingandconsensus).
message CompactOrchardAction {
bytes nullifier = 1; // [32] The nullifier of the input note
bytes cmx = 2; // [32] The x-coordinate of the note commitment for the output note
bytes ephemeralKey = 3; // [32] An encoding of an ephemeral Pallas public key
bytes ciphertext = 4; // [52] The first 52 bytes of the encCiphertext field
}