Query daml templates using the json api

Hello Damlers,

I just want to know if there is a way to query available templates for a ledger.
Currently, i’m using @daml/ledger to fetch users and packages, but i can’t find a way to do the same thing for templates.
Can you suggest a function or an endpoint to handle that.


The JSON API has been designed under the assumption that you are writing a client application for a given set of templates, i.e. you have access to the Daml code of the templates you want to interact with (and use it to generate client-side types through the codegen).

There is no direct way to list templates through the JSON API (or the raw gRPC ledger API, as far as I know). You can list dalfs and download them, and conceivably you could try to parse them and retrieve template information that way. I would strongly recommend against going down that path, though.

It’s a core tenet of Daml that you should know what you’re signing, so having side-channel access to the Daml code is a pretty strong assumption in the way the whole system works.

1 Like

Thank you Gary for the answer.

The app on which i’m working right now will be envolving constantly. Having that in mind, we should somehow reference all the templates somewhere else so we can list them for users.

For the native navigator integration, i can see that the UI uses Graphql to fetch data. However, DAML is not supporting that (or at least for the moment).

The Navigator tool has a backend server that talks to the Ledger API, fetches DALFs, parses them, extracts type information, and exposes the result as a GraphQL endpoint for the browser.

We consider it a dev-time-only tool and, as I said, recommend building client applications against specific templates for production use-cases, so you can know what you’re committing to when you sign a contract or exercise a choice.


Is there any guidance i can follow to read about DALFs and fetching data from them?

The only official, supported documentation I’m aware of is here.

If you’re willing to go off the supported path, there are a couple more options - but you’re definitely on your own at that point.

If you have a Daml compiler available and are willing to shell out to it, you can run daml damlc inspect PATH_TO_DALF --json, then parse the resulting JSON. This JSON format is not documented, not supported, only used internally and may change at any point without notice.

If you’re writing in a JVM language, you can look at the various libraries we have in the Daml repo to read and parse Daml-LF, and see if any one suits your use-case. Readng the code for the Navigator backend may be a good entry point for that, since you seem to want to do something similar. Again, these libraries are internal, not documented, not supported, and may change at any time without notice.

Finally, you could read the Daml-LF specification in the repo, and the LF protobuf definitions, and write your own parser. Again, you’d be on your own.

There may be other options I’m not aware of, but the gist of it is whichever you pick, you’re off the supported path.

Hope that helped, and best of luck should you decide to move forward with this.

1 Like

I encourage you to think about how much your app is like Navigator before committing further research to inspecting Daml-LF.

Navigator is an example of ledger metaprogramming; that is, it’s a tool meant for ledger inspection and interaction, with no idea of what is on the ledger, what it’s supposed to represent, or how it ought to be presented to users.

The trade-off is that it doesn’t “understand” anything about what the templates mean. A template Iou { issuer, owner, amount } is treated exactly the same as a template Foo { bar, baz, quux } if the fields have the same types. They have the same form fields, offer the same options, and use the same display presentation.

This is fine for a completely general ledger tool like Navigator, but is completely wrong for most applications, which ought to be written with the specific semantics of the specific templates they interact with in mind. Which means that whether this will work for your users depends on what kind of app you are building.

So the question is, are you working on a ledger metaprogramming application like Navigator?

If so, I strongly recommend that you do not write the Daml-LF inspection in JavaScript or TypeScript at all. My favored approach would be to follow @Gary_Verhaegen’s suggestion; since we do not support new ledger metaprogramming tools in general, your best chance is to follow our own approach as closely as possible, so that you can refer to our open-source code for hints on how to do things. (I discussed this a little more in a previous thread.)

If you are instead writing an application for a domain, I would suggest searching for a more indirect approach instead of inspecting Daml-LF. For example,

  1. even if you are not using React, it is still proper to be using daml codegen js; if the problem you are having is “the Daml gets updated before the JS app gets updated”, then you might be able to deal with this by inspecting the contents of the code-generated modules.
  2. If the problem is template ID mismatches and you are hand-writing the JS interaction with @daml/ledger instead of taking advantage of daml codegen js, then simply incorporating that into your build would fix the problem immediately, not to mention making your JS app safer.

But it’s really hard to say what would work without knowing the nature of the disconnect between Daml evolution and JS app evolution that you are experiencing.

1 Like