I am in the process of writing a DA Ledger client application. It's going slow because the API documentation does not explain how to combine the provided services to do simple Create, read, update, and delete on the Ledger.
For example there is no simple service that allows the client to read all contacts from a given party directly. First the client needs to get the ledger id, and then (I think) the package id. etc. There is a service to read active contracts, but what about inactive contracts?
It would be helpful to have some documentation that explains and demonstrates how to combine calls to the various services to (for example):
- Read all contracts for a given party
- Exercize a choice on a given contract
- Create a new contract
My application is being written in php. I don't necessarily need examples in php but I just want to know how do use the provided services to accomplish simple tasks.
Read all contracts for a given party
A DAML Ledger is an inherently event-driven system. As such it doesn't provide query access like a traditional database. Instead, your application subscribes to the TransactionService using the GetTransactionsRequest and specifying LEDGER_BEGIN as the begin offset. This will deliver you all Created and Archived events that happened since the ledger was started. In your application you can consume these events to build up a representation (in-memory or persisted) of the ledger, which you can then query conveniently. For example, you could populate a dictionary by contract type, adding an entry for each Created event and removing it again when an Archived event is received.
Create contracts or exercise choices
There are two ways to do this:
Submit a create or exercise command via Submit on the CommandSubmissionService and wait for a success or error message on the CommandCompletionService. Note that receiving such command completion message only confirms that the command could be successfully received by the ledger. It will not contain any effects (create and archive events) from that command. These you will again receive on the TransactionService mentioned above.
Submit a create or exercise command via SubmitAndWait on the CommandService. This service combines command submission and completion in a synchronous call to the server-side, and will therefore only return once the command has been accepted or rejected by the server. It is usually more convenient to use this way of command submission as it takes care of some of the asynchronous event handling required in the previous method.
Note that you can obtain the contract id required to exercise choices from your ledger representation built up using the TransactionService mentioned above.
