@daml/hub-react

React functions for Daml applications running on Daml Hub.

Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

Documentation

This library aims to complement @daml/react, to make it easier to write React applications on Daml Hub specifically.

The @daml/hub-react library can only be used with user interfaces hosted on Daml Hub, it is not supported for local development.

This library exports Typescript declarations, and should work in a Typescript project out of the box.

See the DA Marketplace app as a reference for more advanced usage of this library.

Usage

Login

Any app that runs on Daml Hub needs to authenticate to the ledger. Authentication is done via stateless access tokens that are signed and distributed by Daml Hub, provided in the JSON Web Token format. These tokens expire every 24 hours.

Typically, authentication forwards the user through an interactive sign-in flow then redirects back to the application. The user's access token is then made available to the app via the DAMLHUB_LEDGER_ACCESS_TOKEN cookie.

This library provides the <DamlHubLogin .../> component which handles the redirect flow and cookie extraction automatically. The only required prop is onLogin, which is a callback that gives the party's credentials after a successful login. If there were any errors with authentication, they are provided in the optional second argument of the callback.

Example:

1<DamlHubLogin onLogin={(credential, error) => {
2  if (credential) {
3    /* handle credentials. the application may cache the token and use it for subsequent API calls. */
4    const { party, token } = credential;
5    console.log(party, token);
6  }
7  else { /* handle error */  }
8}}>

The credential object returned in the callback is an instance of the PartyToken class. The application may check the validity of a token at a later point by using the getter credential.isExpired.

Login Methods

For development purposes, it may be wise to test the application with multiple different parties with different roles. In this case, it is possible to specify alternate login methods. There are three methods altogether, with short-form props that can be used to enable them in a mix-and-match fashion:

1. withButton: The primary simple button login, recommended for production applications. Upon clicking, the user is taken through interactive user login flow as described above, for production applications. The login button is used by default if no other props are given. Note that if either of the two other method props are supplied, the button is not displayed unless the withButton prop is also supplied.

2. withFile: Login with a parties.json file. This is a file containing a list of all the parties (and associated ledger access tokens) that you've created under your Daml Hub account for the ledger. It can be downloaded from Daml Hub.

This prop exposes a file input that accepts the JSON file (and validates its fields for correctness, bubbling up any errors to the app). The file is never sent anywhere over the network - it is only parsed via client-side JavaScript, with the aid of the FileReader API.

When using this prop, the extra prop onPartiesLoad must be supplied as a callback to retrieve the entire list of credentials for each party into your application.

1<DamlHubLogin
2  withFile
3  onPartiesLoad={(credentials, error) => {
4    if (credentials) {
5      credentials.forEach(cred => {
6        console.log(cred.party, cred.token);
7      });
8    } else {
9      /* handle error */
10    }
11  }}
12/>

3. withToken: Allow the user to type or paste in an encoded JWT token string directly in a form input, which is then passed back to your app as an instance of PartyToken.

1// Enabling all three login methods
2<DamlHubLogin
3  onLogin={/* ... */}
4  withButton // The default button flow described above
5  withToken // Exposes a text input to paste in a JWT directly
6  withFile // Exposes a button to load in a parties.json file
7  onPartiesLoad={/* ... */} // Get the results from the file loader
8/>

Customization

Some support for customizing the login components is possible. This is obtained by foregoing the short-form props above (withButton, withFile, withToken) and instead using the more generic options prop.

When customizing the file login method, the component supplied is expected to be a <label>. See this StackOverflow post for more details about styling HTML file inputs.

Example:

1<DamlHubLogin
2  onLogin={/* ... */}
3  onPartiesLoad={/* ... */} // Get the results from the file loader
4  options={{
5    method: {
6      button: {
7        render: () => <MyButton myProp1={/**/} myProp2={/**/} />
8        text: 'My Login Button Text',
9      },
10      file: {
11        render: () => <label>{/* ... */}</label>,
12      },
13    },
14  }}
15/>

Logout

Import and call the function damlHubLogout() to log out the user. This function will delete the cookies set by Daml Hub on the application page.

API Hooks

@daml/hub-react exposes a context with which you should wrap around your entire application, <DamlHub token='...'> {/* ... */} </DamlHub>.

Within this context, React hooks become available for interacting with Hub-specific APIs, outlined below. The APIs request/responses are documented in an OpenAPI specification, and are readable on the official API reference page.

APIs that retrieve data are polled and updated every 5 seconds by default. The polling interval can be overridden globally via the <DamlHub ... interval={x}> prop, where x is a number of milliseconds. Use 0 to disable polling.

Default Parties

Daml Hub provides two 'default parties' that are available for lookup by any unauthenticated client. These are Public and UserAdmin. The UserAdmin party is not allocated automatically - this party must first be allocated via the Daml Hub console before showing up.

The party identifiers may be fetched individually as below.

1const publicParty = usePublicParty();
2
3if (!publicParty) {
4  // Still loading
5} else {
6  console.log(publicParty);
7}
8
9const adminParty = useAdminParty();
10
11if (!userAdminParty) {
12  // Still loading, or UserAdmin is yet to be allocated
13} else {
14  console.log(userAdminParty);
15}

The hook useDefaultParties is the same as the above two, but returns both parties at once as an array tuple. This is a helpful shortcut if making heavy usage of both parties.

1const [publicParty, userAdminParty] = useDefaultParties();
2
3if (!publicParty || !userAdminParty) {
4  // Still loading, UserAdmin is yet to be allocated, or something went wrong
5} else {
6  console.log(publicParty, userAdminParty);
7}

Public Party Token

To retrieve the public party token on the ledger (a read-only token that can be used to stream publicly visible contracts), use the following hook:

1const publicToken = usePublicToken();
2
3if (!publicToken) {
4  // Still loading, or something went wrong
5} else {
6  console.log(publicToken);
7}

Automations

Daml Hub supports automations to execute ledger actions automatically. There are three varieties - Daml triggers, Python bots, and integrations. APIs exist to view available automations, deploy instances, and delete running instances.

When deploying instances, they run under the authorization of the logged in party (the token specified in the DamlHub context token prop).

1const { automations, undeployAutomation } = useAutomations();
2const { instances, deployAutomation, deleteInstance } = useAutomationInstances();
3
4console.log(automations);
5console.log(instances);
6
7React.useEffect(() => {
8  // Start a running instance of the specified automation by hash
9  const { id: instance0 } = await deployAutomation(
10    automations[0].artifactHash,
11    automations[0].owner
12  );
13
14  // Start an instance of a trigger-type automation by name
15  const { id: instance1 } = await deployAutomation(
16    automations[1].artifactHash,
17    automations[1].owner,
18    automations[1].automationEntity.value.triggerNames[2]
19  );
20
21  // Undeploy a specific instance
22  deleteInstance(instance1, automations[1].owner);
23
24  // Remove all instances of a certain automation
25  undeployAutomation(automations[0].artifactHash);
26}, []);

Token Utilities

Ledger access tokens come in the form of JSON Web Tokens. The built-in PartyToken class can be used to extract useful data from them. For example:

1const token = new PartyToken('eyJ0eXAiOiJKV1QiLCJh...');
2
3let userParty = token.party;
4let usersPartyName = token.partyName;
5let needToResetLogin = token.isExpired;
6
7// The original JWT string
8let jwt = token.token;

Using hub-react with a custom domain

If you are using this library with a domain that is not provided to you by Daml Hub, you must set nonHubDomain to true in the DamlHub context:

1<DamlHub token="..." nonHubDomain>
2  {/ ... /}
3</DamlHub>

You must also indicate this by passing true into isRunningOnHub if calling it directly.

Build

Releases

To cut a release:

1. Bump the version in package.json, and merge that to main
2. Create a GitHub release. The presence of the tag will trigger a CircleCI run that deploys to npm.