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

Welcome to the Wallet Daml Sample App

The Wallet Sample App is an open-source digital asset wallet powered by Daml smart contracts and Daml/React Javascript library, and deployed in Daml Hub. This app provides developers with a working example of how to implement essential workflows related to digital assets (or tokens) such as asset issuance, airdrop, transfer and atomic swap. We assume the developer already has basic knowledge of Daml.

You can watch the video walkthrough of the application here

You can play around with user functionality in the Wallet Daml Sample App without deploying the app, as it is continuously running at https://wallet.daml.app. To sign in to the app running at https://wallet.daml.app, use your Daml Hub account. You can create a free Daml Hub account, if you don't already have one.

User workflows implemented in Wallet Daml Sample App include the following features

• Creating an asset holding account
• Issuing assets (creating new quantities of an asset in an issuer party account)
• Airdropping assets (creating new quantities of an asset in a non-issuer party account)
• Inviting other users to create their asset holding accounts
• Sending assets to other users (asset ownership transfer)
• Swapping assets (atomic swap - simultaneous transfer of ownership of two assets between two parties) The app is centered around the concepts of asset and asset holding account. To learn about these concepts and their implementation in this app see Wallet Daml Sample App - concepts and their implementation article.

The frontend of the project was bootstrapped with Create React App. However, all Daml specific aspects of the UI client are written in plain TypeScript. The React framework can be easily replaced with any other UI framework.

Prerequisites

• Daml SDK
• Java 11 or higher
• Visual Studio Code
• Node.js

Running the Project Locally

Build Required Files

*The below build steps are also necessary for deploying the app to Daml Hub.

1. On Linux or MacOS from the root of the project run

make build

On Windows, which doesn't have make utility, or if for any reason make utility doesn't work on your Linux or MacOS, run the following commands from the project root directory

cd main/User
daml build -o user.dar

cd ../Asset
daml build -o asset.dar

cd ../Account
daml build -o account.dar

cd ../Setup
daml build -o setup.dar

cd ../../triggers
daml build -o triggers.dar

This will generate the .dar files, which include asset.dar, account.dar, user.dar in their respective folders within the main folder, that need to be deployed to the backend Daml ledger. This will also generate setup.dar and triggers.dar files used to initialize the ledger and for off-ledger automation.

2. On Linux or MacOS from the project root run

make codegen

On Windows, which doesn't have make utility, or if for any reason make utility doesn't work on your Linux or MacOS, run the following commands from the project root directory

daml codegen js  main/Asset/asset.dar main/User/user.dar main/Account/account.dar -o ui/daml.js

The script will generate a daml.js folder in the /ui directory with the JavaScript bindings.

3. Regardless of whether you run Linux, MacOS or Windows, navigate to the ui directory from the project root by running cd ui and then run npm install

Start Backend Processes

On Linux or MacOS from the project root directory run

./start.sh

This script executes several setup operations, but since this is a shell script, it can only be run on Linux or MacOS. If you're running Windows or if you'd prefer to start the backend process manually, click here.

Please note: Each time you make changes to the .daml files, you will need to re-run make build, and make codegen and reinstall the packages on the frontend through npm i, so that the frontend packages and dar files are in sync.

Start the Frontend

After running start.sh shell script, the backend of the app is fully functional. To launch the app GUI, in a separate instance of the terminal cd to the ui directory and run npm start. This should open a browser window with a login screen. If it doesn't, you can manually navigate your browser to http://localhost:3000. When running locally, the app has the following pre-defined users: "alice", "bob", "charlie", "ron". These users are created by the startup Daml Script in Setup.daml module. When prompted to sign-in to the app UI, type in one of the above user names and hit Enter.

Please note: If you use Node v18 or higher you need to replace the following two lines

"start": "react-scripts start",
"build": "react-scripts build",

in the "scripts" section of the ui/package.json file.

• On Linux or MacOS use

"start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
"build": "NODE_OPTIONS=--openssl-legacy-provider react-scripts build",

• On Windows use

"start": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts start",
"build": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts build",

Make sure to save ui/package.json file after editing it and before running npm start.

Starting the Backend Processes Manually

The ./start.sh performs the below operations. On Windows you need to run these operations manually, as described below. On Linux or MacOS you may also prefer to perform these operations manually if you'd like to familiarize yourself with the process of deploying a Daml application.

1. Start the Sandox and upload the dar files.
2. Start JSON API server.
3. Run setup script to allocate parties and create initial contracts (required only for local deployment).
4. Start the 4 triggers.

1. Start the Sandbox & Upload the Dar Files

On Linux or MacOS terminal run from the project root directory

make sandbox

On Windows or if you cannot use make utility copy and paste the below command and run it from the project root directory.

daml sandbox --dar main/Asset/asset.dar --dar main/User/user.dar --dar main/Account/account.dar 

Leave this terminal running.

2. Start HTTP JSON API Service

On Linux or MacOS in a separate terminal run from the project root directory

make server

On Windows or if you cannot use make utility copy and paste the below command and run it from the project root directory.

daml json-api --config json-api-app.conf

Leave this terminal running.

3. Run Setup Script

Regardless of whether you run Linux, MacOS or Windows, in another terminal run the setup script. This script allocates parties, creates an Example Token asset account and Example Token asset contract.

daml script --dar ./main/Setup/setup.dar --script-name Setup:setup --ledger-host localhost --ledger-port 6865

4. Start 4 Triggers

Make sure to run each trigger in a separate instance of the terminal and leave all these terminals running. The instructions in this step apply regardless of the operating system you're running. For details on why the triggers are needed click here

1. From the root directory, start the sendAssetHoldingAccountInviteTrigger by running the following command in another terminal. This trigger sends an invitation to create an Asset Holding Account for Example Token to new users.

daml trigger --dar triggers/triggers.dar \
        --trigger-name SendAssetHoldingAccountInviteTrigger:sendAssetHoldingAccountInviteTrigger \
        --ledger-host localhost \
        --ledger-port 6865 \
        --ledger-user "admin"

2. From the root, in a separate terminal instance, run the below trigger. This trigger allows 'admin' user, which corresponds to the party that is the issuer of the Example Token, to automatically accept airdrop requests for Example Token.

daml trigger --dar triggers/triggers.dar \
             --trigger-name AcceptAirdropRequestTrigger:acceptAirdropRequestTrigger \
             --ledger-host localhost \
             --ledger-port 6865 \
             --ledger-user "admin"

3. From the root, in a separate terminal instance, run the below trigger. This trigger allows 'admin' user, which corresponds to the 'Default Party' that is the issuer of the Example Token, to automatically accept invites to create an Asset Holding Account for user's asset. This invite is created as part of a swap workflow when a user swaps his or her asset for an amount of Example Token with 'admin'.

daml trigger --dar triggers/triggers.dar \
             --trigger-name AcceptAssetInviteTrigger:acceptAssetInviteTrigger \
             --ledger-host localhost \
             --ledger-port 6865 \
             --ledger-user "admin"

4. This trigger allows 'admin' user, which corresponds to the 'Default Party' that is the issuer of the Example Token, to automatically accept asset transfers and swap proposals created by a user.

daml trigger --dar triggers/triggers.dar \
             --trigger-name AcceptSwapTrigger:acceptSwapTrigger \
             --ledger-host localhost \
             --ledger-port 6865 \
             --ledger-user "admin"

Please Note
All the actions in the start.sh shell script are run as background jobs, as they launch processes that need to keep running while the app is being used.

Starting Frontend (not implemented in ./start.sh)

Once the above steps are executed, the backend of the app is fully functional. To start the frontend follow the instructions here.

Trigger Uses

Daml triggers provide automation for certain interactions with the ledger. This project implements 4 triggers, which we need to start. These triggers implement a bot, which provides a party for a human user to swap assets with. When you login as a user to the app frontend for the first time, you automatically receive an invite to create an asset holding account for Example Token (ET). Once you accept the invite, you can request new quantities of the Example Token to be airdropped into your asset holding account. This request is automatically granted. After creating an asset holding account for a new asset type and after issuing a quantity of this asset into your own account, you can invite the 'Default Party' to open an account for this asset. A trigger automatically accepts invites sent to the 'Default Party'. Then you can transfer some quantity of the asset to the 'Default Party' or swap this asset for an amount of Example Token. A trigger automatically accepts transfers and swap proposals sent by a user to the 'Default Party'. All this functionality demonstrates the workflows implemented in the app without requiring another human user to interact with (e.g. trade assets).

Deploying the project to Daml Hub

The app is continuously run on Daml Hub by Digital Asset at https://wallet.daml.app. You can play with user functionality in the app run by Digital Asset. To sign in to the app UI at the above URL use your Daml Hub account. You can create a free Daml Hub account, if you don't already have one. You can also deploy your own version of the app on Daml Hub. First create a free Daml Hub account.

To learn how to deploy Daml apps to Daml Hub see Daml Hub Quickstart

Setup Project on Daml Hub

Once logged in, click Create Project on the right hand side of the hub interface.

You will be asked to provide the project name and the ledger name. Click Continue to move to the next page.

Uploading Dar Files

In this step you need to upload the dar files created in "Build Required Files" step. These include:

• account.dar
• asset.dar
• user.dar
• triggers.dar

For each of the above files click Upload File and navigate to the file location on the local machine.

Upload UI Zip File

In addition we need to create wallet-refapp-ui.zip file by running npm run zip command from the ui directory. This zip file contains the app UI and also needs to be uploaded to Daml Hub by clicking Upload File in the Daml Hub UI.

Once all files that need to be uploaded to the ledger have been selected, click Launch Ledger. This will create the ledger with the name you specified and upload the files. Click on the ledger name under the project created. This will take you to the Deployments page with the actions that need to happen next listed under Action Needed. Note that at this point the files have been uploaded to the ledger, but not yet deployed on it. In other words the Daml models (dar files), Daml Triggers and the UI are ready for deployment, but are not yet running on the ledger. To make them run follow the prompts on the page as described below.

1. Deploy instances of dar files and the UI zip file to the running ledger

It may be that the top action suggested on the lage is to deploy the triggers. In this case scroll down the page until you see account.dar, asset.dar, user.dar and wallet-refapp-ui.zip files. Click Deploy Instance button for each of these files.

2. Configure triggers for Daml Hub

It may take a few minutes for the ledger to initialize. During this time you may see "Loading parties..." in the Party field under the action to deploy Daml Triggers in the triggers.dar. Once the ledger is started you can configure the triggers.

• Under Trigger Name, select the first trigger
• Under Party, select UserAdmin. If UserAdmin party is not listed in the drop-down you may need to refresh the page and select Daml Triggers under the Deployments.
• Click Deploy Instance, and repeat for all other triggers.

Setup Admin Account on the Deployed App

This step initializes the ledger with some data required for the Daml Triggers implemented in this app. Specifically the step sets up the asset holding account for ET (example token) asset, which is issued by the default party (aka UserAdmin party), and which is used to perform automatically accepted and settled swaps with the default party. See Trigger Uses setion for more details. Before the triggers can run properly, you will need to

1. Click the Identities tab and copy JWT for the UserAdmin party
2. Launch the app in the new tab by clicking the Subdomain link in the bottom left corner of the above page. This will open the app login page in a new tab. Click Login with Token button. Login to the app using the JWT of the UserAdmin party
3. On the left hand side menu, click Create. You will arrive at the asset holding account creation page
4. In the symbol field, name the asset ET, then click Create at the bottom to create the ET asset holding account. Once this account is created, other users will be able to receive the automatic ET account asset invitations sent by the triggers, and users will also be able to request airdrops and swap with the UserAdmin.

Now the app is fully set up. You can log out from the app and login by clicking Log into Wallet button in the login page and using your Daml Hub account credentials to sign in. The first time you log into the app as a user you should see an invite to create your asset holding account for ET. Accept the invite and follow the instructions on the right hand side of the app UI to issue your own assets and explore other workflows in the app.