Protocol Documentation

Table of Contents




CompactBlock is a packaging of ONLY the data from a block that's needed to:

1. Detect a payment to your shielded Sapling address

2. Detect a spend of your shielded Sapling notes

3. Update your witnesses to generate new Sapling spend proofs.

protoVersion uint32

the version of this wire format, for storage

height uint64

the height of this block

hash bytes

prevHash bytes

time uint32

header bytes

(hash, prevHash, and time) OR (full header)

vtx CompactTx repeated

compact transactions from this block


cmu bytes

epk bytes

ciphertext bytes


nf bytes


Index and hash will allow the receiver to call out to chain

explorers or other data structures to retrieve more information

about this transaction.

index uint64

hash bytes

fee uint32

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. in a pure-Sapling context, the fee will be calculable as: valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut))

spends CompactSpend repeated

outputs CompactOutput repeated




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.

height uint64

hash bytes


BlockRange specifies a series of blocks from start to end inclusive.

Both BlockIDs must be heights; specification by hash is not yet supported.

start BlockID

end BlockID


Chainspec is a placeholder to allow specification of a particular chain fork.


Duration is currently used only for testing, so that the Ping rpc

can simulate a delay, to create many simultaneous connections. Units

are microseconds.

intervalUs int64


Empty is for gRPCs that take no arguments, currently only GetLightdInfo.


LightdInfo returns various information about this lightwalletd instance

and the state of the blockchain.

version string

vendor string

taddrSupport bool

chainName string

saplingActivationHeight uint64

consensusBranchId string

blockHeight uint64


PingResponse is used to indicate concurrency, how many Ping rpcs

are executing upon entry and upon exit (after the delay).

entry int64

exit int64


RawTransaction contains the complete transaction data. It also optionally includes

the block height in which the transaction was included

data bytes

height uint64


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.

errorCode int32

errorMessage string


TransparentAddressBlockFilter restricts the results to the given address

or block range.

address string

range BlockRange


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.

block BlockID

index uint64

hash bytes


Method NameRequest TypeResponse TypeDescription
GetLatestBlock ChainSpec BlockID

Compact Blocks

GetBlock BlockID CompactBlock

GetBlockRange BlockRange CompactBlock stream

GetTransaction TxFilter RawTransaction


SendTransaction RawTransaction SendResponse

GetAddressTxids TransparentAddressBlockFilter RawTransaction stream

t-Address support

GetLightdInfo Empty LightdInfo


Ping Duration PingResponse

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str