Improve documentation regarding transaction filtering limitations for GetTransactionTrees

[leo-da]

Rescoped, see #1483 (comment)

---

GetTransactionTrees GRPC Service does not support TransactionTree filtering by template ID:

Template filtration is not supported on GetTransactionTrees RPC. To get filtered data, use the GetTransactions RPC.

TODOs:

1. Document GetTransactionTrees GRPC explaining the limitations
2. Document Java bindings com.daml.ledger.rxjava.TransactionsClient#getTransactionsTrees
3. Document Scala bindings com.digitalasset.ledger.client.services.transactions.TransactionClient#getTransactionTrees

I also think we should:
a). deprecate the existing GetTransactionTrees GRPC Service:

  // Read the ledger's filtered transaction stream for a set of parties.
  rpc GetTransactions (GetTransactionsRequest) returns (stream GetTransactionsResponse);

  // Read the ledger's complete transaction tree stream for a set of parties.
  rpc GetTransactionTrees (GetTransactionsRequest) returns (stream GetTransactionTreesResponse);

It takes the same GetTransactionsRequest message as GetTransactions service. However it cannot handle template_ids defined in TransactionFilter message.
b). define new messages: GetTransactionTreesRequest and TransactionTreeFilter
c). define a new Transaction Tree service as:

  rpc GetTransactionTreesV2 (GetTransactionTreesRequest) returns (stream GetTransactionTreesResponse);

where GetTransactionTreesRequest message doe NOT allow passing template_ids.

[leo-da]

Or can we break the backward compatibility?

[bitonic]

While I agree that the current behavior is not so nice since it's not discoverable from the .proto definitions only, I do not think it's worth breaking backwards compatibility because of this. We've never actually heard a complaint about this, BTW.

However, I just checked and the documentation for this is severely lacking: the .proto files do not even mention this, as far as I can tell. This should definitely be fixed.

[gerolf-da]

The doc for GetTransactionsRequest#filter states that templates must be empty for the GetTransactionTrees method.