Using Switchboard

This is a walk-through covering the main functionality of Switchboard released to date. It assumes you already have a wallet in either (i) a WalletConnect-compatible mobile application or (ii) the MetaMask browser extension.

The alpha release of Switchboard leverages the Energy Web Volta test network. Therefore, all chain transaction fees use Volta tokens, which have no value and are freely obtainable from a faucet. We encourage you to experiment with this alpha release and become familiar with what Switchboard can do for you, so that when we release the production version of Switchboard on the Energy Web Chain you already know how you wish to use it.

Please note that some privacy-related browser extensions could cause problems with Switchboard. Therefore, if you find that you are unable to complete a step described below, please try disabling your privacy extensions and reloading the page.

 


I. Visiting the Switchboard landing page

Using a web browser on your computer, visit the Switchboard landing page. It should appear similar to the image below.

[Optional] Installing Switchboard as app on your mobile device

Switchboard is a progressive web app, meaning that if you access the Switchboard website via a browser on your mobile device, you can add Switchboard as an app on your device’s home screen (without using the app store or play store).

To do this, first open your browser and navigate to the Switchboard landing page.

Using Chrome on an Android device, click the three-dot overflow menu in the upper-right corner to reveal a menu similar to that shown at right. Click on “install app” to initiate the download. You should then see the Switchboard logo as an app on your home screen.

On an iOS device, the process is similar. Navigate to the Switchboard landing page in Safari, then tap the “share” button and scroll down to “add to home screen.” Switchboard will now appear on your home screen.


II. Connecting to your wallet

As noted above, you may connect to Switchboard using either a WalletConnect-compatible mobile wallet app (on your mobile device) or a MetaMask browser extension. Each of these methods is described below. You can complete either one and skip the other option.

A. Mobile wallet

This step requires that you have two devices: a primary device (e.g., a computer) with a browser displaying the Switchboard landing page, and a mobile device (tablet or smartphone) on which you have installed a WalletConnect-compatible application.

First, on your primary device, click “use mobile wallet” to view a QR code similar to that in the image at right. Next, on your mobile device, open the mobile application you use as a wallet, and use that mobile app to scan the QR code on your primary device’s screen.

The app on your mobile device will ask you to confirm that you wish to connect to Switchboard. Your mobile app might then ask you to sign one or more messages. Finally, your mobile app might ask to confirm the connection. After signing and confirming as instructed in your mobile app, your primary device should automatically bring you to the Switchboard main screen, which should appear similar to the image shown in part C below.

B. MetaMask browser extension

This step requires that you already have installed the MetaMask browser extension and created a wallet in MetaMask. See the page on using the MetaMask browser extension for more details.

When you click the “use MetaMask” button, the MetaMask browser extension should open automatically. After you sign in to MetaMask, click the “connect” button. You will be requested to sign a message; do this to complete the connection to Switchboard. You should land on Switchboard’s main screen, which should appear similar to the image shown in part C below.

C. Switchboard main screen

The December 2020 alpha release of Switchboard contains functionality related to governance (managing organizations, application, and roles) and enrolments (qualifying to take on a role in a decentralized application). Near future releases of Switchboard will add functionality related to assets (managing and enroling one’s assets in decentralized applications), services (managing utilities such as decentralized storage or messaging), and applications (searching for and installing decentralized applications).


III. Updating your profile

The first thing to do in Switchboard is to update your profile. Click the “Manage Profile” link in the upper right corner of the screen, then click “Update Identity” in the menu.

You should see a pop-up window similar to the image at right. Complete the fields and click the “update” button. Your mobile app might ask you to confirm or sign one or more steps.

You can return to this identity pop-up at any time, should you wish to update your information.


IV. Managing organizations, applications, and roles

One set of functionality in Switchboard relates to governance: managing organizations and applications. To explore this, click on the “governance” button from the Switchboard main screen. You should see a governance dashboard similar in appearance to the image below.

Switchboard leverages the Energy Web Name Service (an implementation of the Ethereum Name Service for Energy Web). With EWNS, you can organize your organization, any applications your organization owns/operates, and all roles within your organization or those applications.

The alpha release of Switchboard is built on Energy Web’s Volta test chain. As you set up your organization, applications, and roles in the alpha version, these will be anchored to Volta. We hope that you test out all available functionality, but we also recommend that you do not enter any sensitive information into the fields at this time. For example, when you create an application in part B below, use a test name if you wish to keep secret the real name of your application for now.


A. Organization management

The first tab within governance relates to organization management. Here, you can perform several functions related to your organization and its EWNS namespace, each using the buttons under the “actions” column. Those actions are described below and assume that you already own an organization.

The alpha release of Switchboard does not allow you to create a new organization and its namespace. Instead, Energy Web has created an organization for each Energy Web member, and we will transfer ownership of that namespace to you whenever you provide us the address you wish to use.

Symbol

Name

Description

Symbol

Name

Description

View details

View the basic details of your organization, including the logo, namespace, organization name, website, description, and other data.

Edit details

Change the details of your organization. Please note that it is not possible to change the root namespace of an organization. For example, after you have defined “exampleco.iam.ewc” as your namespace, you could define subdomains (e.g., “roles.exampleco.iam.ewc” or “applications.exampleco.iam.ewc”), or you could define a new root namespace (e.g., “exampleorg.iam.ewc”), but you are not able to change the root namespace “exampleco.iam.ewc” into something different.

The “others (JSON)” field allows you to specify formatting-related details (e.g., color scheme) that should be applied, so that when you integrate Switchboard into your decentralized applications the branding is consistent. For example, you could add into this field the text:

1 {"bgcolor":"CDD3FF","txtcolor":"FF0000"}

The above text will set the background color for Switchboard in your application to be the light blue color with hex code CDD3FF and the text color to be red with hex code FF0000. You can experiment with different formatting options.

Transfer ownership

Transfer ownership of your organization and its root namespace to another address.

View applications

View the applications owned by this organization (i.e., go to application management tab).

Create application

Create a new application owned by the organization.

View roles

View the roles associated with this organization or with any application owned by this organization (i.e., go to role governance tab). Note that that are two kinds of roles:

  1. Roles associated with an organization - these roles are independent of any particular application. For example, you might create the role “global dApp admin” to manage all of your organization’s applications.

  2. Roles associated with an application - these roles are specific to a particular application. For example, you might create the role “installer” or “renewable energy buyer” in an application that you own. These roles are not necessarily part of your organization.

Create role

Create a new role associated with either this organization or a specific application owned by this organization.

Delete organization

Delete your organization (not recommended during alpha release, as you do not have the ability to create a new organization).

In future releases of Switchboard, it will be possible to create a new organization. As part of this, you will set the namespace for your organization; this means the subdomain that will appear within the identity and access management (IAM) section of the EWNS directory (e.g., “exampleco” in the root namespace “exampleco.iam.ewc” shown in the image above).

In future releases of Switchboard, it also will be possible to create sub-organization namespaces. This will allow you to define applications and roles for specific subsidiaries or business units within your organizational umbrella. For example, you might create “subsidiary1.exampleco.iam.ewc” and “subsidiary2.exampleco.iam.ewc” so that you can define applications and roles specific to those subsidiaries (as described in the following sections of this document).

B. Application management

After you have created an organization and set its root namespace, you may wish to set the namespace for decentralized applications your organization will own/operate. To do this, click on the second tab, application management, as shown in the image below.

The first step is to create the new application namespace, using the “create application” button on the right. You will then see a pop-up with several fields to complete. Starting with step 5 of this process (registering the namespace for the app), you will be asked to confirm the transaction using your linked wallet.

Note that any application namespace you define will automatically be created under an “apps” subdomain within your organization’s namespace. For example, if your organization’s namespace is “exampleco.iam.ewc” and you wish to create a new subdomain for an application you call “DERmanager,” then your resulting namespace will be “dermanager.apps.exampleco.iam.ewc” (the “apps” subdomain is added automatically, to organize applications separately from other subdomains).

After you have completed all steps to create the new application, your application management tab should appear similar to the image below.

You have several possible actions, similar to your options under organization management. Note that you also have the option to filter your applications by organization; this may be helpful if, for example, different subsidiaries within your corporate umbrella wish to manage applications separately, but you as a designated superadmin need to be able to view all of them.


C. Role governance

The final governance task is perhaps the most powerful use of Switchboard, and it builds on the organization and application management functionalities described above. It is governance related to roles—not only roles within your organization but also roles that different users might have in your applications.

When you first visit the role governance tab, it should appear similar to the image below.

As noted above, Switchboard allows you to define two types of roles:

  1. Roles associated with an organization - these roles are independent of any particular application. For example, you might create the role “global dApp admin” to manage all of your organization’s applications.

  2. Roles associated with an application - these roles are specific to a particular application. For example, you might create the role “installer” or “renewable energy buyer” in an application that you own. These roles relate to your application but are not necessarily part of your organization.

We will create each type of role here. Start by clicking the “create new role” button on the right side of your screen. You will see a creation window that should look familiar if you have created an application (it is also similar to the window to create a new organization, which will be possible in a future release). The first field requires you to specify the role type: organization or application.

1. Organization role type

You may create an organization role only if you are the owner of your organization. You will be prompted to complete a field defining the namespace for the new role. Any such role will automatically be created within the domain “roles.[your organization].iam.ewc”. Using our example, the role “superadmin” will be created at “superadmin.roles.exampleco.iam.ewc” automatically.

Critically, as part of the role definition process you will be prompted to set the role issuers for your new role. Recall that Switchboard is designed as a decentralized system for role management, so nobody at Energy Web or any other centralized authority is responsible or empowered to control which users (DIDs) may have which roles. Instead, when you define a role, you must specify what a DID must be able to prove to you, in order for that DID to take on a certain role in your application. This proof comes in the form of a claim verified to be true by some other party (the latter being the issuer of the claim about the DID).

Example. Imagine you create a new organization owned by a multi-signature wallet, and you want to create a new superadmin role with rights across your entire organization, so that certain actions can be performed without requiring multiple signatures. You could set up the superadmin role’s issuer as the multi-signature wallet, so that the authorized owners of that multisig wallet could designate specific users to act as these superadmins (and, of course, remove such a designation if desired). In that case, you could specify the issuer type as a specific DID, and specify the address of the multi-signature wallet as the only DID that can act as the issuer of the superadmin role.

Alternatively, you might prefer that anyone with a particular role would have authority to approve the enrolment of other DIDs into this new role. For example, imagine you have created the superadmin role as described above, but now you wish to create a new role for other employees of your organization, employee, with more limited rights. You could specify that anybody who has the role of superadmin could approve the enrolment of employees, so that it is not necessary for the multi-signature wallet to approve every employee user. In this way, when a new DID requests to enrol as an employee, the request may be approved quickly by any superadmin.

After you specify the issuer(s) for the role, you have the ability to set fields. This means that you can specify the data fields that a user (DID) must provide when requesting to enrol in that role. For example, you might add the fields “family name,” “given name,” and “email address” so that any new user must provide this information as part of the enrolment process, and so that the issuer will see this information when the issuer receives the enrolment request.

After you work through the remaining steps in the “create role” window, you should see the new organization role listed in your role governance screen, similar to the image below.

2. Application role type

You may create an application role only if you are the owner of that application. You will follow a similar process to that described above for an organization role.

You will be prompted to complete a field defining the namespace for the new role. Any such role will automatically be created within the domain roles.[your app].apps.[your organization].iam.ewc. Using an example, the role “installer” will be created at “installer.roles.appexample.apps.exampleco.iam.ewc” automatically. As described in section 1 above regarding organization role types, you must specify the issuer for each role you create. You have the ability to specify the issuer as a specific DID or a role, and note that you can specify either a role at the organization level or a role at the application level.

Example. Imagine your organization is owned by a multi-signature wallet and has created the role superadmin to expedite setting up applications. You have connected to Switchboard with your own wallet and successfully enroled as a superadmin (with the approval of the multisig).

You set up a new application with the roles app admin and battery owner. You could specify that the role app admin must be approved by anyone with the organizational role superadmin, but that the app role battery owner is approved (issued) by anyone with the app admin role. In this way, you can easily establish role governance for applications that leverage either organizational (cross-application) roles or application roles, depending on what makes sense in you specific situation.

After you complete the creation of the new application role, you will see that application role listed on your role governance screen (see “Installer” example in the image below).

Note the icons to the right of your new application role. When you click the rightmost icon, you will copy a link to a URL that others can use to enrol in your application as that role type. You will try this in the next section of this document below.


V. Enrolments

Users of Switchboard can use the enrolments functionality in two ways. Recall that, because Switchboard uses a decentralized system of identity and access management, any person can own a DID and add claims verified by authorities, which are then used to take on roles in applications. This system of enrolment has three key users:

  1. An authority (issuer) who can verify claims about users, so that the users can add the verified claims to their DID documents (and use them to enrol in an application).

  2. Users who request claims from authorities, so that the users can add the verified claims to their DID documents.

  3. The owner of an application, who specifies what claims (content of the claim, and from whom) are required in order to enrol in that application.

Example. Imagine you wish to deploy an application related to electric vehicle smart charging. Your application might include the roles of vehicle owner, vehicle manufacturer, and vehicle dealer. In order for a DID to enrol in your application as a vehicle owner, you might require a verified claim from a vehicle dealer that this DID is in fact the person to whom it sold a particular vehicle (you might require many more claims, including claims from the manufacturer about the vehicle’s model, identification number, battery capacity, and other things, but let us keep the example simple for now). In this example, you can use Switchboard to set up these roles and requirements: a DID can enrol in you application as a vehicle owner only if it has a verified claim from a dealer that the DID is the owner of the vehicle.

Returning to the work you have done so far, you have set up the required claims and issuers in part IV. Now let us see how a new user can enrol in an example application. First, ensure you have the URL you copied in part IV.C.2. above. Next, open a new browser window, and paste that URL in the navigation bar. This will load the sign-in page, and you can sign in with your existing address (i.e., the same DID and thus same user) or create and sign in with a new wallet address (simply create one in your mobile wallet or MetaMask browser extension), if you wish to test this from the perspective of a new user. Either way, you will see an enrolment screen similar to the example below.

If you wish to use more than one DID, then it is recommended to either (a) use a different browser for each user or (b) use a browser extension that manages multiple sign-ins to a single website, such as SessionBox.

When you complete these fields and register, Switchboard sends the enrolment request to the issuer(s) who had previously been specified to approve the role (see part IV.C.2. above). In the meantime, you can view this pending role request on your “my enrolments” screen, which should appear similar to the image below.

Return now to your sign-in as the issuer who can approve the role. Your enrolments screen should display the request from the new user, as shown in the example below.

Use the icon under the “actions” header to approve or reject the request. If you approve this request, you have issued a verified claim that the new user can add to that user’s DID document and thereby access your application in the appropriate role.

Return one final time to the new user’s sign-in. You should see a screen similar to the image below.

Note that the status now shows that your enrolment has been approved. Finally, you should add this newly issued claim to your DID document, so that you have the credentials you need in order to access the application with the appropriate role. Use the rightmost icon under the “actions” header to add the claim to your DID document.


VI. Searching for organizations and applications

Because Switchboard leverages EWNS, it is instantly possible for any user to search for organizations and applications that have defined namespaces.

To see an example, return to the main landing page by clicking on the Switchboard logo in the top left of your browser window. You screen should appear similar to the image below.

In the search bar below your name and address, enter any search term. Try “flex” for an example. Switchboard will display all organizations and applications that have the word “flex” in their EWNS namespaces. Of course, during this alpha release on Volta, you are likely to see many examples and test applications, at least in the sort term. When you click on any of these, you will see the relevant public information associated with this namespace. For example, clicking on the the Energy Web Flex (example) “application” displays information about that app, including the roles defined in that app’s namespace. In this way, you can view what roles (user types) are part of a given application.

You can even request to enrol your DID in one of these roles directly from this screen, using the action buttons in the roles list at right. You enrolment request will be submitted to the relevant issuer, as defined by that app owner via the process described in Part IV of this document.


VII. Conclusion

In completing the above walk-through, it should start to become apparent how Switchboard can simplify and accelerate application deployment: the functionality to create DIDs, set up roles and role governance, and authenticate users is already available to you.

Taking this further, you might imagine integrating this functionality seamlessly into your own application, so that users can enrol directly in your app without navigating away from it. You also might imagine that, as more users and devices create their own DIDs, enrolments become even easier, as a single verified claim might be reused across a variety of applications. This network effect could further accelerate app adoption.

Example. Imagine the owner of an electric vehicle wishes to enrol in an EV charging application. To do this, the owner must create a DID and obtain verified claims from the seller that the owner actually owns the vehicle and from the vehicle manufacturer that the vehicle has certain battery and charging specifications.

Now imagine you create a new application relating to EV smart charging (shifting the time of charging events, based on price signals or grid congestion data). In order to allow EV owners to enrol in your application, you might accept the same claims from the EV seller and EV manufacturer. This means that, once the EV owner has obtained these claims and added them to the EV owner’s DID document, it is simple for that owner to also enroll in your app. This shows how app adoption could be accelerated by claims that are specific to a DID but not specific to an application, as is the case with Switchboard.


VIII. Known issues

  1. When creating a new role, if you set the issuer type to role (as opposed to a DID), but no DIDs have enrolled into that issuer role, the system will not permit you to continue with the role creation. This will be addressed in a future version, because it should be possible to define the issuer type as role even if no DIDs already have that role.

  2. When creating a new application or role, you must be careful to omit any spaces before or after any EWNS string (e.g., “exampleapp.apps.exampleco.iam.ewc”), because including a space before or after the string will prevent the system from advancing to the next step. This field will be replaced by a more user-friendly field (auto-complete / pull-down) in an upcoming release.

  3. The IAM client library contains the code:

1 2 3 4 5 _iam = new IAM({ rpcUrl: rpcurl, chainId: chainid, cacheClient: undefined //cacheClient })

This can produce an error if there is no child process. If you experience this error, try adding the code:

1 2 3 4  "browser": {    "child_process": false,    "fs": false  }