Calling shared functions

One of the most important features of the Internet Computer for developers is the ability to build, deploy, and call shared functions in one canister from a program in another canister. This capability to make calls between canisters—also sometimes referred to as inter-canister calls—enables you to reuse and share functionality in multiple applications.

For example, you might want to create an application for professional networking, organizing community events, or hosting fundraising activities. Each of these applications might have a social component that enables users to identify social relationships based on some criteria or shared interest, such as friends and family or current and former colleagues.

To address this social component, you might want to create a single canister for storing user relationships then write your professional networking, community organizing, or fundraising application to import and call functions that are defined in the canister for social connections. You could then build additional applications to use the social connections canister or extend the features provided by the social connections canister to make it useful to an even broader community of other developers.

The Motoko-based LinkedUp sample application provides a simple implementation of an open professional network that demonstrates how to use inter-canister calls within a project.

In the LinkedUp sample application, there are two canisters:

The linkedup canister creates and stores basic profile information for a user, including work experience and educational background.
The connectd canister creates and stores a user’s connections.

Download the demo

To experiment with inter-canister calls using the LinkedUp sample application:

Open a terminal shell and change to the folder you are using for your Internet Computer sample projects.

Clone the linkedup repository.

git clone git@github.com:dfinity-lab/linkedup.git

Change to the local working directory for the linkedup repository.
```
cd linkedup
```
Install node modules by running the following command:
```
npm install
```

Build and deploy the demo project

To build and deploy the LinkUp sample application, take the following steps:

Build the canisters by running the following command:
```
dfx build
```
Start the Internet Computer network replica by running the following command:
```
dfx start
```
Open a terminal and change to the linkedup repository directory.
Deploy the project on the local network by running the following command:
```
dfx canister install --all
```
You should see canister identifiers for both the connectd canister and the linkedup canister with a message similar to the following:
```
Installing code for canister connectd, with canister_id ic:321B70FF148808B210
Installing code for canister linkedup, with canister_id ic:FC4106BF7A7A63D1CE
```
Copy the linkedup canister identifier returned by the dfx canister install command.

In this sample application, only the linkedup canister includes the front-end assets used to access the application’s features. To open the application in a browser, therefore, you need to specify the linkedup canister identifier.

Create a profile and connections

To run through a demonstration of the LinkedUp sample application, take the following steps:

Open a browser tab or window.
Type the web server host name, port, and the canisterId keyword, then paste the linkedup canister identifier as the URL to display.
```
localhost:8000/?canisterId=<ic-identifier-for-linkedup>
```
The browser displays an introductory page.

A public-private key pair will be automatically generated to establish your identity for accessing the canister, so there’s no need to provide a user name and password or register an account to store your identity before using the service.
Click Login.

The browser displays an empty profile page.
Click Edit, type profile information, copy and paste the image address for an avatar photo, then click Submit.

While you are interacting with the sample application, you might notice records similar to the following capture your activity and are displayed in the terminal you used to start the replica process:
```
Apr 14 20:34:57.614 INFO Successfully inserted an ingress message into IngressPool, Application: ArtifactPool
Apr 14 20:34:58.564 INFO Created checkpoint @6921 in 33.579754ms, StateManager: 1
```
After you click Submit, you have a profile with some work history that can be viewed.

For example:

Add another profile

At this point, there are no other profiles to search for or to add as connections. To try out the Search and Connect features, you can:

Run a script that populates the sample application with some additional profiles.
Create a profile manually by opening a private window.

For this tutorial, you will create another profile manually.

To add a user profile with different identity:

At the top right of the browser window, click the appropriate icon to display the browser’s menu options.

For example, if you are using Google Chrome, click the vertical ellipse to display the More menu.
Click New Incognito Window if you are using Google Chrome or New Private Window if you are using Firefox to enable you to navigate to the canister without the user identity generated in your initial browser connection to the canister.
Copy and paste the URL from your first browser session into the private browsing window, then click Login.

Notice that there’s no profile in the private browsing window but your original profile is still visible in your initial browser tab.
Click Edit, type profile information, copy and paste the image address for an avatar photo, then click Submit.

After clicking Submit, you have a second profile with some work history that can be viewed.

For example:
Type the first name or last name from the first profile you created—for example, if you created a profile for Maya Garcia, type Maya—then click Search.

The profile matching your search criteria is displayed.
Select the contact from the search results, wait for the Connect button to be displayed, then click Connect.

When the connection request completes, the second profile displays the connection to the first profile. For example:
Return to the browser tab with your original profile.

If you want to create a connection between the original profile and the profile you created in the private browsing window, you can do so by repeating the search, select, and connect steps.

Save identity information for the incognito profile

Currently, user identities get generated when a user connects to a canister using a device such as a browser running on a laptop. You used an incognito browser window to create a second LinkedUp profile. If you close that private browsing window, the incognito user identity will no longer be available.

This section demonstrates how user identities are currently associated with a canister and stored by the browser. You might find the information useful for testing programs that involve more than one user. Keep in mind, however, that this specific approach is only a temporary solution for handling authentication and user identities.

To illustrate saving the incognito user identity, take the following steps:

At the top right of the browser window, click the vertical ellipse to display the More menu.
Click More Tools, then select Developer Tools to display the developer tools explorer.
Click Application, expand Local storage, then select the host name and port running the LinkedUp application.
Copy the Value of the dfinity-ic-user-identity key.

The dfinity-ic-user-identity key value stores the public and private keys for the user.
Return to the standard browser window.

For example, the window that displays the Maya profile.
Click the vertical ellipse to display the More menu, click More Tools, then select Developer Tools to display the developer tools explorer.
Click Application, expand Local storage, then select the host name and port running the LinkedUp application.
Rename the dfinity-ic-user-identity key to preserve the existing public-private key.

For example, rename the dfinity-ic-user-identity to maya-dfinity-ic-user-identity.
Add a dfinity-ic-user-identity key and paste the value from the incognito user to save the incognito user’s identity in the browser.
Refresh or close and reopen the browser window, then click Login to log in using the profile you created in the incognito window.
Open another incognito window, type Maya in the Search field, then click Search to see that Maya’s profile and connections are persisted.

You can create another new profile or close the incognito window.

Explore the configuration file

Now that you have explored the basic features of the sample application, you have some context for exploring how the configuration settings and source files are used.

To explore the configuration file:

Change to the linkedup directory, then open the project’s dfx.json file.
Note that there are two canisters defined—connectd and linkedup—each with a main.mo source file.
Note that the linkedup canister specifies a frontend entry point of main.js and assets in the form of CSS and HTML files.
Note that the application uses the default server IP address and port number.

Explore the connectd source code

The source code for the social connections canister, connectd, is organized into the following files:

The digraph.mo file provides the functions to create a directed graph of vertices and edges to describe a user’s connections.
The main.mo contains the actor and key functions for defining the connections associated with a user profile that can be called by the LinkedUp sample application.
The types.mo file defines the custom type that maps a vertex to a user identity for use in the digraph and main program files.

Explore the linkedup source code

The source code for the professional profile with work history and educational background is organized into the following files:

The main.mo file contains the actor and key functions for the LinkedUp sample application.
The types.mo file defines the custom types that describe the user identity and profile fields that are imported and used in the main program file for the linkedup canister.
The utils.mo file provides helper functions.

Query and update operations

In working with the LinkedUp sample application, you might notice that some operations—such as viewing a profile or performing a search—returned results almost immediately. Other operations—such as creating a profile or adding a connection—took a little longer.

These differences in performance illustrate the difference between using query and update calls in the linkedup canister.

For example, in the src/linkedup/main.mo file, the create and update functions are update calls that change the state of the canister, but the program uses query calls for the get and search functions to view or search for a profile:

  // Profiles

  public shared(msg) func create(profile: NewProfile): async () {
    directory.createOne(msg.caller, profile);
  };

  public shared(msg) func update(profile: Profile): async () {
    if(Utils.hasAccess(msg.caller, profile)) {
      directory.updateOne(profile.id, profile);
    };
  };

  public query func get(userId: UserId): async Profile {
    Utils.getProfile(directory, userId)
  };

  public query func search(term: Text): async [Profile] {
    directory.findBy(term)
  };

Interaction between the canisters

In this sample application, the linkedup canister leverages functions defined in the connectd canister. This separation simplifies the code in each canister and illustrates how you can extend a project by calling common functions defined in one canister from one or more other canisters.

To make the public functions defined in one canister available in the another canister:

Add an Import statement in the calling canister.

In this example, the public functions are defined in the connectd canister and are called by the linkedup canister.

Therefore, the src/linkedup/main.mo includes the following code:
```
// Make the Connectd app's public methods available locally
import Connectd "canister:connectd";
```
Use the canister.function syntax to call public methods in the imported canister.

In this example, the linkedup canister calls the connect and getConnections function in the imported connectd canister.

You can see the code that enables interaction between the linkedup canister and the connectd canister in the main.mo source files.

For example, the src/connectd/main.mo defines the following functions:

actor Connectd {
  var graph: Digraph.Digraph = Digraph.Digraph();

  public func healthcheck(): async Bool { true };

  public func connect(userA: Vertex, userB: Vertex): async () {
    graph.addEdge(userA, userB);
  };

  public func getConnections(user: Vertex): async [Vertex] {
    graph.getAdjacent(user)
  };

};

Because of the Import statement, the connectd functions are available to the linkedup canister and the src/linkedup/main.mo includes the following code:

  // Connections

  public shared(msg) func connect(userId: UserId): async () {
    // Call Connectd's public methods without an API
    await Connectd.connect(msg.caller, userId);
  };

  public func getConnections(userId: UserId): async [Profile] {
    let userIds = await Connectd.getConnections(userId);
    directory.findMany(userIds)
  };

  public shared(msg) func isConnected(userId: UserId): async Bool {
    let userIds = await Connectd.getConnections(msg.caller);
    Utils.includes(userId, userIds)
  };

  // User Auth

  public shared query(msg) func getOwnId(): async UserId { msg.caller }

};