From 568d7b7860ec0b848cb84474f38b25bed890de09 Mon Sep 17 00:00:00 2001 From: lucretius Date: Mon, 15 Jan 2024 17:46:10 +0100 Subject: [PATCH] update proto files --- lib/proto/compact_formats.proto | 45 +++++++++----- lib/proto/service.proto | 100 +++++++++++++++++++++++++++----- 2 files changed, 115 insertions(+), 30 deletions(-) diff --git a/lib/proto/compact_formats.proto b/lib/proto/compact_formats.proto index 7e1bc54..cecce25 100644 --- a/lib/proto/compact_formats.proto +++ b/lib/proto/compact_formats.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package cash.z.wallet.sdk.rpc; -option go_package = "walletrpc"; +option go_package = "lightwalletd/walletrpc"; +option swift_prefix = ""; // 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. @@ -11,11 +12,11 @@ option go_package = "walletrpc"; // 3. Update your witnesses to generate new Sapling spend proofs. message CompactBlock { uint32 protoVersion = 1; // the version of this wire format, for storage - uint64 height = 2; // the height of this block - bytes hash = 3; - bytes prevHash = 4; - uint32 time = 5; - bytes header = 6; // (hash, prevHash, and time) OR (full header) + uint64 height = 2; // the height of this block + bytes hash = 3; // the ID (hash) of this block, same as in block explorers + bytes prevHash = 4; // the ID (hash) of this block's predecessor + uint32 time = 5; // Unix epoch time when the block was mined + bytes header = 6; // (hash, prevHash, and time) OR (full header) repeated CompactTx vtx = 7; // compact transactions from this block } @@ -23,8 +24,8 @@ message CompactTx { // Index and hash will allow the receiver to call out to chain // explorers or other data structures to retrieve more information // about this transaction. - uint64 index = 1; - bytes hash = 2; + uint64 index = 1; // the index within the full block + bytes hash = 2; // the ID (hash) of this transaction, same as in block explorers // The transaction fee: present if server can provide. In the case of a // stateless server and a transaction with transparent inputs, this will be @@ -33,16 +34,32 @@ message CompactTx { // valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut)) uint32 fee = 3; - repeated CompactSpend spends = 4; - repeated CompactOutput outputs = 5; + repeated CompactSaplingSpend spends = 4; + repeated CompactSaplingOutput outputs = 5; } +// 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) +} + +// output is a Sapling Output Description as described in section 7.4 of the +// Zcash protocol spec. Total size is 948. +message CompactSaplingOutput { + bytes cmu = 1; // note commitment u-coordinate + bytes epk = 2; // ephemeral public key + bytes ciphertext = 3; // first 52 bytes of ciphertext +} + +/* message CompactSpend { - bytes nf = 1; + bytes nf = 1; // nullifier (see the Zcash protocol specification) } message CompactOutput { - bytes cmu = 1; - bytes epk = 2; - bytes ciphertext = 3; + bytes cmu = 1; // note commitment u-coordinate + bytes epk = 2; // ephemeral public key + bytes ciphertext = 3; // first 52 bytes of ciphertext } +*/ diff --git a/lib/proto/service.proto b/lib/proto/service.proto index e5719ad..aa52e39 100644 --- a/lib/proto/service.proto +++ b/lib/proto/service.proto @@ -1,7 +1,7 @@ syntax = "proto3"; package cash.z.wallet.sdk.rpc; -option go_package = "walletrpc"; - +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 @@ -56,14 +56,13 @@ message LightdInfo { uint64 longestchain = 9; uint64 notarized = 10; } - message Coinsupply { string result = 1; string coin = 2; - int64 height = 3; - int64 supply = 4; - int64 zfunds = 5; - int64 total = 6; + uint64 height = 3; + uint64 supply = 4; + uint64 zfunds = 5; + uint64 total = 6; } message TransparentAddress { @@ -75,28 +74,97 @@ message TransparentAddressBlockFilter { BlockRange range = 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 Hush getblockmerkletree rpc. +// https://faq.hush.is/rpc/getblockmerkletree.html +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 +} + +// 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 { - // Compact Blocks + // 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) {} + // Return a list of consecutive compact blocks rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {} - // Transactions + // 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) {} - // t-Address support + // Return the txids corresponding to the given t-address within the given block range + rpc GetTaddressTxids(TransparentAddressBlockFilter) returns (stream RawTransaction) {} + // wrapper for GetTaddressTxids rpc GetAddressTxids(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) {} - // Misc + 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) {} rpc GetCoinsupply(Empty) returns (Coinsupply) {} - - //Mempool - rpc GetMempoolTx(Exclude) returns (stream CompactTx) {} - rpc GetMempoolStream(Empty) returns (stream RawTransaction) {} -} +} \ No newline at end of file