Using Switchboard
This is a walk-through covering the main functionality of the system released to date. It assumes you already have a wallet in either a WalletConnect-compatible mobile application or MetaMask browser
Last updated
This is a walk-through covering the main functionality of the system released to date. It assumes you already have a wallet in either a WalletConnect-compatible mobile application or MetaMask browser
Last updated
-> The test version of the system leverages the Energy Web Volta test network. Therefore, all chain transaction fees use Volta tokens, which have no value and are freely obtainable from the Volta faucet. Here you can try and become familiar with what the system can do for you.
-> The production version of the system is on the Energy Web Chain and uses Energy Web Tokens for transactions. You can view the cost of transactions for each operation using this link.
We recommend using Switchboard on Chromium (Google Chrome, Brave, etc.) or FireFox browsers.
Please note that some privacy-related browser extensions could cause problems with the system. Therefore, if you find that you are unable to complete a step described below, please try disabling your privacy extensions and reloading the page.
Using a web browser on your computer, visit the system landing page. It should appear similar to the image below.
The system is a progressive web app, meaning that if you access the system website via a browser on your mobile device, you can add the system as an app on your device’s home screen (without using the iOS App Store or Google Play Store).
To do this, first, open your browser and navigate to the system 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 the right. Click on “install app” to initiate the download. You should then see the system logo as an app on your home screen.
On an iOS device, the process is similar. Navigate to the welcome page in Safari, then tap the “share” button and scroll down to “add to the home screen.” the system will now appear on your home screen.
As noted above, you may connect to the system 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.
This step requires that you have two devices: a primary device (e.g., a computer) with a browser displaying the system 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 the 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 the system. 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 dashboard screen.
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 the system. You should land on the Switchboard dashboard screen.
The Switchboard dashboard contains functionality related to assets (creating managing an asset DID), governance (managing organizations, applications, and roles), and enrolments (issuing, viewing and revoking roles).
If you click "Manage Profile" button on the top right corner of the dashboard, you can access the user profile menu.
You can add a human-readible name label to your DID account using this menu item. The name is only stored locally and viewable by you.
DIDs are not very human-readible and hard to memorize, therefore you can use the DID Book function to store the most used DIDs with labels to access them quickly.
You can use this function to scan DID encoded QR Codes.
You can use this function to see the DID document in raw JSON format and copy it.
You can use this function to logout from the current DID account.
An asset is a virtual representer of the user’s solar panels, smart energy meters, batteries and other devices in the system. Each asset is assigned its own DID that gives them the ability to be a part of the Energy Web Network, so they can be transferred or enrolled in a role.
By clicking on the “Register Asset” button on my assets tab, you add one more asset to your list. It will get its own DID automatically.
You should see a general list of assets similar in appearance to the image below.
As an owner, you can perform several options under the three vertical dots button (next to the last updated date in the list).
Symbol
Name
Description
View Ownership History
View the history of owners and transaction of chosen asset.
Verification Method
Existence of the asset can be verified by a third-party. For this you should know the third-party public DID and type of Network.
Transfer Ownership
Transfer ownership of your asset. For this you should know public DID of a new owner. As soon as a request submited your asset from My assets tab will be moved to Previously owned assets.
Edit
At any time, you can set a personal name and icon for each of your items. For security reasons, assets names are blurred in the general list.
Generate QR-Code
Generate a QR-code for a chosen asset.
Issue Claim to Asset
Inform about Verified Claim of a chosen asset.
Assets can be enroled to a role credential. By clicking on the Enrolments button (next to the asset name) you can see all roles that the chosen asset has. We recommend adding this issued claim to the asset's DID document so that you have the credentials you need in order to access the application with the appropriate role, you can use the Publish button to do this operation.
One set of functionality in the system relates to governance: managing organizations and applications. To explore this, click on the “governance” button from the system main screen. You should see a governance dashboard similar in appearance to the image below.
The system 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 development version of the system is built on Energy Web’s Volta test chain. As you set up your organization, applications, and roles, 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.
The first tab within governance relates to organization management.
If you haven’t had an organization yet, you can add it by clicking on the “Create Organization” button. The system asks you to fill the form and submit the request.
The “Create Organization” button allows creating only one organization per wallet. After using, the button is hidden from UI.
Assume that you already own an organization, on the Organization management tab you can perform several options related to your organization and its EWNS namespace, each using the options under the three vertical dots button (next to an organization namespace in the list).
Symbol
Name
Description
View Details
View the basic details of your organization, including the logo, namespace, organization name, website, description, and other data.
Create Sub-Organization
Create a new sub-organization owned by the organization. This allows 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).
View Applications
View the applications owned by this organization (i.e., go to application management tab).
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:
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.
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 Application
Create a new application owned by the organization.
Create Role
Create a new role associated with either this organization or a specific application owned by this organization.
Edit
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 the system 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 the system 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.
Delete
Delete your organization.
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.
The first step is to create the new application namespace, using the “create an application” option on the organization management tab. 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 the organization; this may be helpful if, for example, different subsidiaries within your corporate umbrella wish to manage applications separately, but you as a designated super admin need to be able to view all of them.
The final governance task is perhaps the most powerful use of the system, 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.
As noted above, the system allows you to define two types of roles:
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. This role is created under your organization or chosen sub-organization on the Organization management tab.
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. This role is created under your application on the Application management tab.
For creating a role, you should fill the role definition form. You can find detailed explanation of the each step below;
At this step, you will choose an unique role name to host the role definition, full domain path will be shown including application and organization names. The system will prompt if the name is already in-use.
At this step, you will select who is allowed to issue this role. As a role definition creator, your DID will be listed as an issuer by default. You can easily override it by adding another DID or even a role name.
At this step, you will select who is allowed to revoke this role. As a role definition creator, your DID will be listed as a revoker by default. You can easily override it by adding another DID or even a role name.
At this step, you can define a precondition for the user to request this role from the issuer. The user needs to obtain the precondition role and publish it to its DID document and afterwards can continue to requesting this role.
At this step, you can define a default validity period to guide the issuers. The issuers have authority to override it at the time of the issuence.
At this step, you can create custom input fields that will be used to collect data from the user at the time of the role request. This data is only for the issuer to get some more information about the user before the issuence. The data is not stored on the role credential.
At this step, you can create custom input fields that will be used to collect data from the issuer at the time of the issuence. The data will be stored on the role credential.
When you have at least one role, the role governance tab should look similar to the image below.
Each role in the list has the same list of options: View Details, Edit and Copy Role Enrolment URL. The first two are the same as we described above. By choosing the latter one you will copy a link to a URL that others can use to enroll as that role type. You will try this in the next section of this document below.
Users of the system can use the enrolments functionality in two ways. Recall that, because the system 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:
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 enroll in an application).
Users who request claims from authorities, so that users can add the verified claims to their DID documents.
The owner of an application, who specifies what claims (the content of the claim, and from whom) are required in order to enroll 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 enroll 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 the system to set up these roles and requirements: a DID can enroll 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. Now let us see how a new user can enroll in an example application. First, ensure you have the enrolment URL. 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 the 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, the system sends the enrolment request to the issuer(s) who had previously been specified to approve the role.
Return now to your sign-in as the issuer who can approve the role. The issue will be informed about the new request by Task Manager in the top navigation. The notification’s bubble disappears as soon as the task has been completed.
Your enrolments screen should display the request from the new user.
“View Request” pop-up under the three vertical dots button contains information about the requestor, chosen role, and the fields from the enrolment form. 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 can view this pending role request on your “my enrolments” screen, which should appear similar to the image below.
You can add this newly received role credential to your DID document and publish it to on-chain ClaimManager smart contract, so that you have the credentials you need in order to access the application with the appropriate role. Use the “Publish” button, in order to publish the role credential.
You can also revoke a role credential if your DID is listed as one of the revokers. In order to revoke a role credential, you should navigate to "Revocable Enrolments" tab and click "Revoke Off-Chain Enrolment" or "Revoke On-Chain Enrolment" to revoke.
Because the system 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 system logo in the top left of your browser window. Your 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. The system will display all organizations and applications that have the word “flex” in their EWNS namespaces. You are likely to see many examples and test applications. When you click on any of these, you will see the relevant public information associated with this namespace. For example, clicking on 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 enroll your DID in one of these roles directly from this screen, using the action buttons in the roles list at right. Your enrolment request will be submitted to the relevant issuer, as defined by that app owner via the process described in Part V of this document.
