Skip to main content

Sample dApp Template

At Arcana Network, we would like to help dApp developers get started quickly.




This video tutorial demonstrates how you can create a new dApp say, 'Arcana Drive', by using a sample demo app template as a starter kit and integrate a typical dApp with Arcana Auth and Storage SDKs.

The sample demo app template does not have all the integration code in place but there are comments to guide you through the process. Consider it like an empty Vue application shell with cues on where and how to integrate with Arcana SDKs.

info

Refer to the sample dApp template sources here:

https://github.com/arcana-network/demo-app-template

Once you plug in Arcana SDKs the SDK initialization code appropriately in this sample dApp template, it can perform the following functions:

  1. Onboard dApp users via Google social OAuth

  2. Allow dApp users to upload and download file data to Arcana Store

  3. Enable user data privacy and security for any data access operations such as:

    • Share a file with another user
    • Revoke Access to a shared file
    • Delete file
    • Change file owner
    note

    All the storage access operations are powered by Arcana Network blockchain. The dApp user must sign/approve the blockchain transaction before any file access operation can happen.

Get Started​

caution

Prerequisites

Steps​

At a high level, here is what you need to do before you can start editing code in the sample dApp template.

There are two parts. First you need to use Arcana Network Dashboard and configure your dApp settings. And second, you need to use the sample dApp template sources and follow the instructions in this tutorial to integrate it with Arcana Network SDKs.

As part of configuration, you need to perform the following actions:

  • Register your dApp using Arcana Dashboard
  • Set up Google OAuth using Google Console
  • Configure your dApp Auth with data obtained from Google OAuth and also configure Arcana Store settings or choose defaults.

After completing dApp configuration, you need to get the sources. Follow the steps and update the sample dApp template code to integrate Arcana SDKs.

Step 1: Register your dApp via Arcana Developer Dashboard​

  • Begin by registering your dApp with Arcana Network at:

    https://dashboard.beta.arcana.network

  • Login into the Arcana Dashboard and create a new account for your sample dApp template by specifying a dApp name. For details, see how to configure a dApp guide.

  • Next, specify configuration details for your dApp and choose the desired user onboarding experience. For this tutorial, we will choose social authentication via Google OAuth as the user onboarding mechanism. This will allow dApp users to sign in using their existing Google account.

  • Click on the Auth tab in Arcana Dashboard:

    https://dashboard.beta.arcana.network/app/configure/auth

    Dashboard Auth Tab

  • Refer to the redirect URI listed on the Auth tab towards the right. Here is how the redirect URI will look like:

    https://verify.beta.arcana.network/verify/{your-app-id>}/

    This redirect URI value will be required to setup Google OAuth in the next step. You can click on the copy icon and save the redirect URI to the clipboard.

    Do not close this browser tab. We need to return to the Auth tab of Arcana Network Dashboard and fill in details from Google OAuth setup in the next step.

Step 2: Use Redirect URI from Dashboard and Setup Google OAuth​

  • Open a new browser tab or window and visit Google Console and create new Google OAuth Client ID for your dApp.

    Google OAuth ClientID create

  • In the Google Console, set the Authorized JavaScript Origin to the value:

    http://localhost:3000

    Use the redirect URI saved to clipboard earlier and specify it as the Authorized redirect URI value in the Google Console. Click Save and a new ClientID is assigned for your dApp.

    Google OAuth ClientID copy

  • In the Google Console, click on the copy icon and save this Client ID to the clipboard. You need to specify this ClientID in the Arcana Network Dashboard.

Step 3: Configure ClientID, Wallet UI mode in Arcana Dashboard​

Google ClientID​

Wallet UI Mode​

  • In the Arcana Dashboard Auth tab, after the Social Auth section ClientID setup, you need to scroll down to the Wallet section and Enable the Wallet UI mode toggle.

    Wallet UI Mode

  • Click Save to save your dApp configuration. After your save your dApp configuration on the Arcana Dashboard, your dApp is assigned a unique appID. This is used during Arcana SDK initialization later.

  • To refer to the appID value at any later time, browse this link:

    https://dashboard.beta.arcana.network/app/dashboard

    info

    Arcana dashboard allows dApp developers to manage the user experience for signing blockchain transactions pertaining to user data storage operations. This is controlled using the WALLET UI setting in the Auth tab of the dashboard.

    By default, WALLET UI mode is set to Disabled. What this means is there will be no pop up UI that requires the user to sign every file storage access operation (share, delete, revoke access, change owner). In this case, the end user experience is very similar to the typical Web2 applications without losing on any security or benefits of blockchain.

    Once the UI mode is enabled using the dashboard setting, it cannot be disabled later or reconfigured due to security reasons.

    Besides the dashboard setting, there is another control that works in tandem with the dashboard setting to tweak the blockchain transaction signing behavior.

    The dApp developer can choose appMode during Auth SDK initialization function call. Once WALLET UI setting is enabled through the dashboard, the dApp developer can use appMode in the dApp code when integrating with the Auth SDK. The appMode parameter in the Auth SDK initialization function controls the popup UI type configuration that shows up for dApp users.

    Typically, once coded in the dApp it should not be changed. See wallet mode for details on how different appMode choices can control popup UI behavior and user experience for blockchain transaction signing.

    For step by step instructions see how to configure Wallet UI guide.

Optional dApp Settings​

  • Besides the configurations listed above, you can optionally choose to brand your dApp by setting up your logo image. Click on the General tab on the dashboard to configure these optional settings.

  • You can also update the storage bandwidth and usage limits per dApp user through the Store tab on the dashboard. See how to configure dApp for details.

Step 4: Get Sources​

  • After configuration of dApp using Arcana Network Dashboard, you need to get sources for sample dApp template and update it. Use the commands listed below to clone the sample dApp template sources locally in your local clone path:

    git clone https://github.com/arcana-network/demo-app-template
    cd demo-app-template/

  • Then install dependencies.

    npm install

  • Next, install Arcana Auth and Storage SDKs:

    // For wallet
    npm install @arcana/auth

    // For storage
    npm install @arcana/storage

  • Now it is time to start the development server. After starting the development server, you can continue to update the code using instructions in the next step.

    npm run dev

Step 5: Update sample dApp template​

  • Add code to integrate sample dApp template with Arcana Auth SDKs. Refer to sample dApp template sources and make updates to this file: <your local clone path>/src/services/auth.service.js

  • Import the Auth SDK as shown below:

    /// AUTH-IMPORT: Import arcana auth
    import { AuthProvider } from "@arcana/auth";

  • After importing, create a new instance of Arcana AuthProvider:

    // AUTH-1: Create a new instance of Arcana AuthProvider.
    const auth = new AuthProvider([your-app-id]);
    info

    In the code above, your-app-id refers to the appID copied from the Arcana Dashboard earlier.

    There are additional optional parameters that you can specify in the AuthProvider constructor. For example, network parameter is set to Arcana "Testnet" by default. The inPageProvider parameter is a boolean that ensures window.ethereum value is updated with standard Ethereum provider obtained through AuthProvider.

    For more details, see:

    Arcana Auth SDK Reference Guide

  • Once auth.service is setup, we can use this service in auth composable. Refer to the file: your local clone path/src/use/arcanaAuth.js in the sample dApp template sources. To use this service in auth composable, call the init method of auth.service.

    // AUTH-2: Initialise and configure the auth service.
    // a) Initialise the auth service
    await auth.init({
      appMode: 2,
      position: "right",
    });

  • After initialization, begin listening for the disconnect message. This message is sent by the auth.service when a dApp user logs out:

    // b) Set a disconnect listener. On disconnect, clear store,
    //    route to login and perform a refresh
    auth.provider.on("disconnect", async () => {
      store.dispatch("clearStore");
      router.push("/login");
      router.go();
    });

  • Before calling any other functions from the Arcana Auth SDK, first check if user is already logged in:

    // AUTH-3: Check if a user is logged in
    const loginStatus = await auth.isLoggedIn();

  • Initiate user login with selected login type in response to a user login action. For this tutorial, the login type is Google:

    // AUTH-4: Login user with selected social login type
    await auth.loginWithSocial(type);

    Once the user is logged in, fetch user details and his wallet details:

    // AUTH-5: Fetch user details
    const userInfo = await auth.getUser();

    // AUTH-6: Fetch user's wallet address
    const [walletAddress] = await auth.provider.request({
      method: "eth_accounts",
    });

  • You can add the following code in order to logout a user:

    // AUTH-7: Logout a user
    await auth.logout();

  • You can also use Arcana Auth SDK to obtain the public key of a user by specifying their email.

    // AUTH-8: Get public key associated with the email
    return await auth.getPublicKey(email);

    All these functions above can be plugged into the sample dApp template file: your local clone path/src/services/auth.service.js to enable Google authentication and onboard dApp users.

  • So far we have successfully integrated the Arcana Auth SDK with sample dApp template. Now let us integrate with Arcana Storage SDK using the file: <your local clone path>/src/services/storage.service.js. To integrate with Storage SDK, import it as shown below:

    /// STORAGE-IMPORT : Import arcana storage standalone
    import { StorageProvider } from "@arcana/storage/dist/standalone/storage.umd";

  • After importing, instantiate the Storage SDK:

    // STORAGE-1: Create an instance of Arcana StorageProvider.
    storage = new StorageProvider({
      appId: [your-app-id],
      provider: window.arcana.provider,
    });

  • Once storage.service is setup, it is time to use this service in the storage composable. Refer to the file: <your local clone path>/src/use/arcanaStorage.js in your sample dApp template sources. Call the init method of storage.service as shown below:

    // STORAGE-2: Initialize the storage instance
    StorageService.init();

  • The Arcana Storage SDK is now instantiated and initialized. You can further add code to the sample dApp template and call other functions offered by the Storage SDK. To fetch the usage limits configured for dApp users (storage limit and bandwidth limits), you need to first obtain access to the Arcana Store using the following code:

    // STORAGE-3: Fetch storage limits
    // a) Get the access object from storage instance
    const access = await storage.getAccess();

    // b) Get upload limit and download limit using this access object
    const [storageUsed, totalStorage] = await access.getUploadLimit();
    const [bandwidthUsed, totalBandwidth] = await access.getDownloadLimit();

  • Here is how you can obtain a list of files owned by the dApp user:

    // STORAGE-4: Get files owned by the user from storage instance
    const myFiles = await storage.myFiles();

  • Obtain the list of files shared with the user by other dApp users:

    // STORAGE-5: Get files shared with the user from storage instance
    const sharedFiles = await storage.sharedFiles();

  • You can add the following code to upload a file to the Arcana Store:

    // STORAGE-6: Upload a file
    // a) Get uploader object from storage instance
    const uploader = await storage.getUploader();

    // b) Handle progress, success and error events
    uploader.onProgress = onProgress;
    uploader.onSuccess = onSuccess;
    uploader.onError = onError;

    // c) Upload a file and get the did
    const did = await uploader.upload(file);

  • Download a file from the Arcana Store using the code:

    // STORAGE-7: Download a file
    // a) Get downloader object from storage instance
    const downloader = await storage.getDownloader();

    // b) Handle progress and success events
    downloader.onProgress = onProgress;
    downloader.onSuccess = onSuccess;

    // c) Download a file
    await downloader.download(file.did);

  • Get the list of users with whom a particular file owned by a dApp user is shared with:

    // STORAGE-10: Get list of users, the file is shared with
    // a) Get access object from storage instance
    const access = await storage.getAccess();

    // b) Get shared users
    const sharedUsers = await access.getSharedUsers(did);

  • Delete a file:

    // STORAGE-8: Delete a file
    // a) Get access object from storage instance
    const access = await storage.getAccess();

    // b) Delete the file using access object
    await access.deleteFile(file.did);

  • Share a file with another user using the recipient's email id:

    // STORAGE-9: Share a file
    // a) Get public key of user using his email
    const publicKey = await requestPublicKey(email);

    // b) Compute wallet address using public key
    // NOTE: Import computeAddress from @arcana/auth like
    // import { computeAddress } from '@arcana/auth'
    const address = computeAddress(publicKey);

    // c) Get access object from storage instance
    const access = await storage.getAccess();

    // d) Share a file to this address
    await access.share(file.did, address);

  • Revoke access to a shared file by specifying the file's DID identifier:

    // STORAGE-11: Revoke access to a shared file
    // a) Get access object from storage instance
    const access = await storage.getAccess();

    // b) Revoke share access
    await access.revoke(fileToRevoke.did, address);

  • Transfer ownership of the file to another user:

    // STORAGE-12: Transfer ownership of the file
    // a) Get public key of user using his email
    const publicKey = await requestPublicKey(email);

    // b) Compute wallet address using public key
    // NOTE: Import computeAddress from @arcana/auth like
    // import { computeAddress } from '@arcana/auth'
    const address = computeAddress(publicKey);

    // c) Get access object from storage instance and
    const access = await storage.getAccess();

    // d) Transfer ownership of this file to that address
    await access.changeFileOwner(fileToTransfer.did, address);

  • Once you have added code snippets for the functions listed above, your sample dApp template is a fully functional and integrated dApp. It has all the code plugged in to use Arcana Auth and Storage SDK for ensuring dApp user data privacy and access control powered by Arcana Network blockchain.

    Your dApp is now ready onboard users via Google OAuth as configured in this tutorial. Users can upload and download files or share them depending upon the functions that you have enabled in your integration steps above.

Congratulations!!! You now have a dApp that is integrated with Arcana SDKs. 🎉

Easy, wasn't it? A piece of cake.

Questions?

You can contact Arcana Support using one of the listed mechanisms.

See Also​

Last updated on by shalz