diff --git a/proto/compact_formats.proto b/proto/compact_formats.proto index 8718f1d..ee3b07d 100644 --- a/proto/compact_formats.proto +++ b/proto/compact_formats.proto @@ -1,36 +1,20 @@ syntax = "proto3"; package proto; -// Remember that proto3 fields are all optional. - -// A BlockFilter message contains identifiers to select a block: either a -// height or a hash. -message BlockFilter { - uint64 blockHeight = 1; - bytes blockHash = 2; -} - -message RangeFilter { - BlockFilter start = 1; - BlockFilter end = 2; -} - -// A TxFilter contains the information needed to identify a particular -// transaction: either a block and an index, or a direct transaction hash. -message TxFilter { - BlockFilter blockID = 1; - uint64 txIndex = 2; - bytes txHash = 3; -} - +// Remember that proto3 fields are all optional. A field that is not present will be set to its zero value. +// bytes fields of hashes are in canonical little-endian format. // 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. message CompactBlock { - BlockFilter blockID = 1; - repeated CompactTx vtx = 3; + uint32 protoVersion = 1; // the version of this wire format, for storage + uint64 height = 2; // the height of this block + bytes hash = 3; // the hash of this block + uint32 time = 4; // the block time + bytes header = 5; // OR send the full header + repeated CompactTx vtx = 6; // compact transactions from this block } message CompactTx { @@ -40,8 +24,15 @@ message CompactTx { uint64 index = 1; bytes hash = 2; - repeated CompactSpend spends = 3; - repeated CompactOutput outputs = 4; + // 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)) + uint32 fee = 3; + + repeated CompactSpend spends = 4; + repeated CompactOutput outputs = 5; } message CompactSpend { @@ -53,21 +44,3 @@ message CompactOutput { bytes epk = 2; bytes ciphertext = 3; } - -// An opaque blob of full transaction data, for fetching anything that is not -// in the compact format (e.g. the memo field). -message FullTransaction { - TxFilter txID = 1; - bytes data = 2; -} - -// Empty placeholder. -// Someday we may want to specify e.g. a particular chain fork. -message ChainSpec {} - -service CompactTxStreamer { - rpc GetLatestBlock(ChainSpec) returns (BlockFilter) {} - rpc GetBlock(BlockFilter) returns (CompactBlock) {} - rpc GetBlockRange(RangeFilter) returns (stream CompactBlock) {} - rpc GetTransaction(TxFilter) returns (FullTransaction) {} -} diff --git a/proto/service.proto b/proto/service.proto new file mode 100644 index 0000000..7807766 --- /dev/null +++ b/proto/service.proto @@ -0,0 +1,50 @@ +syntax = "proto3"; +package proto; + +// A BlockID message contains identifiers to select a block: a height or a +// hash. If the hash is present it takes precedence. +message BlockID { + uint64 height = 1; + bytes hash = 2; +} + +// BlockRange technically allows ranging from hash to hash etc but this is not +// currently intended for support, though there is no reason you couldn't do +// it. Further permutations are left as an exercise. +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. +message TxFilter { + BlockID block = 1; + uint64 index = 2; + bytes hash = 3; +} + +message FullTransaction { + TxFilter txID = 1; + bytes data = 2; +} + +message SentTransaction { + bytes data = 1; +} + +message SendResponse { + int32 errorCode = 1; + string errorMessage = 2; +} + +// Empty placeholder. Someday we may want to specify e.g. a particular chain fork. +message ChainSpec {} + +service CompactTxStreamer { + rpc GetLatestBlock(ChainSpec) returns (BlockID) {} + rpc GetBlock(BlockID) returns (CompactBlock) {} + rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {} + rpc GetTransaction(TxFilter) returns (FullTransaction) {} + rpc SendTransaction(RawTransaction) returns (SendResponse) {} +}