A framework of UX rules for Blockchain based Distributed Applications (part 1)
Note: This post is quite long > jump to the cheatsheet 📌 or to the conclusions
Blockchain developers are pushing forward the grand vision of a decentralized future, but the experience of that vision through the Distributed Applications (Dapps) we are crating still resembles a clunky prototype of the web2.
It is probably fitting that most of the users who would use these Dapps still “live” in the web2 and haven’t even heard of the promises of the decentralized Web3.
Even if they were to come and see these shiny new apps, they would have a hard time, from understanding the lingo, the purpose, the dynamics of these Dapps, to even visually tell them apart from normal web apps.
It must be said that there are lot of good tools (Drizzle, MetaMask) that are coming out and are attacking some of these issues. We will get there.
These Design Principles want to propose some ideas on how to fix this, with guidelines to help designers and developers, so that we can all make that shiny future more approachable and near, for everybody.
Web3 Design vs Blockchain Design
Other people have written on “Blockchain Design”[1], while presenting solutions relating to the front-end user experience of Decentralized Apps (Dapps).
Although Sarah Mills’, lead designer at Consensys, article is an inspiring read and she is clearly the leading voice calling for designers in the Blockchain space, I think that the wording “Blockchain Design” is more appropriate to define the properties, and their interactions, of the Blockchain construct itself: things like the consensus algorithm, the supply base, the block rewards, turing completeness, computation/”gas” cost, on or off chain governance mechanisms and many more.
In this article I will be referring instead to “Web3 Design”, indicating mainly principles that should be applied to the creation of the user facing parts of Decentralized Apps.
It is tempting to use the word “Blockchain” in the title, but that would be clickbait 😉
Why Web 3 Design Principles
Today a user can interact with a Smart Contract deployed on the Blockchain in several ways: either directly via command line, through the form-like interfaces of their digital wallet or Dapp browser, or maybe through the richer front-end that the Smart Contract developer has or will develop.
It is obvious that the path to mass adoption of Dapps goes through the latter: providing a rich user interface unified with the experience of dealing with a Blockchain based Distributed Application.
Today as developers we are, righteously, very busy building the infrastructure of the Blockchain and the Smart Contracts of our projects, so it is obvious that not many Dapps currently have a usable front end or, if they have one, safe for the content, they are mainly indistinguishable from any other web app around.
However Dapps are fundamentally different from normal web or mobile apps because they are based on, and should strongly convey, the powerful principles enabled by the Blockchain: decentralization, transparency, trustlessness, immutability, uncensorability etc.
These properties of the Blockchain, and by reflection of the front-end Dapps, are what these Design Principles codify into usable tools.
The objective is that, once applied correctly, a user that lands on a Dapp can immediately tell she is interacting with one and, more importantly, has access to the powerful properties of the Blockchain and therefore knows she can trust every interaction with the application.
Variables to consider to understand the principles
- the main target in mind is a non-technical user, although some principles are geared towards more savvy users too
- not all Dapps need all principles
- the solutions shown in the examples are just some initial ideas to start the conversation
- some principles could be implemented in different ways by each Dapp developer
- some web3 principles suggest the need for an external tool, service or library rather than imagining that each developer would implement their solution (more on this in the next steps)
- most if not all web3 Design Principles would benefit from being codified in a Bootstrap like developer friendly library (more on this in the next steps)
If you are interested in this, jump to the “next steps” section at the end to see how we can work together.
Approach to Design
Design is also about anticipating problems and offering solutions. In this case I tried to “project” (a better word in my opinion for it’s etymological meaning of “launching forward” into the future) the questions that a user might have when interacting with a Dapp.
Questions like:
- is it safe to do this (action_dapp_asks_me_to_do)?
- will money be at risk if I screw up?
- I’ve heard crypto is supposed to be more private…what happens to the data I send? where will it be stored? Can I be identified?
- who will see the data I input? where is the code being run?
- what will happen after I do this (action)?
- how am I supposed to do (crypto_action_here)?
- what does this (weird_crypto_word) mean?
- Supposedly the Blockchain can be trusted, but how can I tell which data can be trusted on this app?
- which data comes from the Blockchain?
- how can I verify that the data is really stored in the Blockchain?
etc.
The Design Principles provide tools for developers to answer to these and more questions that users might have.
Web 3 Design Principles (index / cheatsheet)
This post is quite long so you can use this cheatsheet to have a quick view of the principles and jump to the ones you are more interested in understanding
//// TTT: Trust Through Transparency Design Principles
1 — (Reading Data) Transparency of Data Provenance
➤ 🌀 Clarify which data comes from the Blockchain and which doesn’t
➤ 🌀 Clarify the address of the contract(s)
➤ 🌀 Link all Blockchain data to independent Blockchain explorers
➤ 🌀 Clarify which data comes from oracles (∞link > 5.Transparency of code)
— How > examples
2 — (Writing Data) Transparency of Transactions
- Types of Transactions (value transfers, function calls, contract generating)
➤ 🌀 [Permanence] clarify actions that are irreversible
➤ 🌀 [Value] clarify actions that involve money or value
➤ 🌀 [Privacy] clarify actions that could potentially lead to user identification
➤ 🌀 [Factory] clarify actions that generate new contracts in the users name
- Guidelines for all transactions:
— ➤ 🌀 clarify and confirm in advance the new future State
— ➤ 🌀 show the data that is being used for a transaction in a human readable format and in the way the Smart Contract requires it (∞link 5.Transparency of Code)
— ➤ 🌀 clarify suggested values for gas price and how to overwrite the Tx (∞link 9.Gas Price and Transaction Reversals)
— ➤ 🌀 manage Transaction wait time (∞link > 6.Time/Wait Management)
— ➤ 🌀 possibly, clarify what actions are NOT transactions and hence safe
— How > examples
3 — (Pushed Data) Transparency of Smart Contract Events
➤ 🌀 clarify and make accessible to the end user all Events, even if they are just for developer purposes
➤ 🌀 apply relevance: show interrupting messages only for information relevant to the current user
➤ 🌀 allow users to subscribe-to, unsubscribe-from or temporarily mute certain events
— How > examples
4 — (History) Transparency and Accessibility of user’s interaction History
➤ 🌀 provide a history of all transactions from a given address
➤ 🌀 clarify where is the history stored (local or server) (∞link 5.Transparency of Code)
➤ 🌀 provide tools to navigate, search, export, and delete the history cache
— How > examples
5 — (Code & Environment) Transparency of Code
➤ 🌀 clarify which Blockchain is being used
➤ 🌀clarify the address of the Smart Contract(s) used in read/write operations
➤ 🌀 clarify which code is open source (and where to find it)
➤ 🌀 clarify where code is being run (local vs remote server)
➤ 🌀 clarify the web3 provider / Blockchain node (local node, Dapp controlled node, MetaMask, Infura, etc)
➤ 🌀 clarify if the Dapp is running on MainNet or TestNet
➤ 🌀 clarify which data comes from oracles or has been influenced by oracles (∞link > 1.Transparency of Data Provenance)
➤ 🌀 allow for DIY code execution: allow advanced users to see the code being run and self execute it via command line
➤ 🌀 clarify the inputs required by the Smart Contracts
— How > examples
//// General Web3 UX Principles
6 — Time/Wait Management
➤ 🌀 (Manage the user’s expectation) clarify Blockchain specific times and manage user’s wait in various phases
➤ 🌀 (Manage the waiting time) Show liveness indicators during waiting time
— How > examples
7 — Human Readable Hashes formats
➤ 🌀 show a compact versions of the hashes but always show the initial and end parts
➤ 🌀 i̵f̵ ̵y̵o̵u̵ ̵n̵e̵e̵d̵ ̵a̵n̵ ̵e̵v̵e̵n̵ ̵s̵h̵o̵r̵t̵e̵r̵ ̵v̵e̵r̵s̵i̵o̵n̵ ̵p̵r̵e̵f̵e̵r̵ ̵t̵h̵e̵ ̵e̵n̵d̵i̵n̵g̵ ̵t̵o̵ ̵t̵h̵e̵ ̵b̵e̵g̵i̵n̵n̵i̵n̵g̵
➤ 🌀 always prepend the “0x” to indicate that it’s a hash
➤ 🌀 allow users to expand the full address/hash
➤ 🌀 allow users to easily copy it
➤ 🌀 where possible use shorthands as titles and the abbreviated addresses as subtitles
➤ 🌀 if possible allow the user to easily associate a custom human readable name or text to the addresses and hashes
➤ 🌀if possible associate some form of deterministic visual representation of the hash (ie Identicons, blockies et al) along with the address
8 — Permanent Newbie Mode
➤ 🌀 weave in educational information with normal interaction
➤ 🌀 provide 2 or more levels of educational content: Blockchain basics and Dapp specific lingo
➤ 🌀 minimize and increase progressively the amount of new things and concepts that the user needs to learn
➤ 🌀 if possible or relevant, accelerate learning providing the “expert’s interpretation”
➤ 🌀 don’t loose context
— How > examples
9 — Gas Price and Transaction Reversals
➤ 🌀 clarify what is Gas and Gas price (just like with any other lingo ∞link 8.Newbie mode)
➤ 🌀 suggest gas prices ranges and clarify time approximations for the upper and lower bounds
➤ 🌀 possibly show gas values converted also to FIAT
➤ 🌀 allow for Transaction Reversals
//// DDP: Decentralization Design Principles
10 — Sense of community
➤ 🌀 clarify how many other members are there in the community
➤ 🌀 clarify who are the other members (choose appropriate categories)
➤ 🌀 clarify the composition of the community (i.e. sub-groups and their power over the project)
➤ 🌀 share the greater mission of the project (if any) and how the user’s participation contributes to its achievement
— How > examples
11 — Future Design Principles to investigate (Part2)
➤ Identities and Reputation
➤ Governance
➤ Wallets
➤ Exchanges
➤ ICO & Token Sales Mechanics
➤ Token Mechanics
Next Steps
TTT: Trust Through Transparency Design Principles
Web3 Postulates:
- It isn’t transparent if you don’t know where & how to look
- If it isn’t transparent it can’t be trusted!
Everybody in this space, and their mother, talks about how the Blockchain is “trustless” and “transparent”.
To explain why these two assumptions are only partially true would take a longer post and make this one err out of track.
It is (almost) certainly true at a programmatic level, software verifying data, but those two assumptions fall apart when you confront them with the actual end user experience.
Besides the fact that many crypto projects or Dapp front-ends seldom show to the user the Smart-Contract addresses she is interacting with or where the data comes from, it currently is daunting or impossible for a non technical user to understand the information and workings of independent Blockchain explorers like Etherscan.
The only thing that is partially controllable today by the user is when intermediating wallets record the transaction hash which can be checked in the aforementioned Blockchain explorers.
Therefore, if a user, especially a non technical one, can’t recognize by looking at the UI if a Dapp is actually a Dapp or a normal web app, nor can she verify if the contents she is seeing, or her interactions with it are actually related to a Blockchain, then she isn’t granted the trustlessness and transparency that the Blockchain is supposed to deliver.
The Web3 Design principles in this category (TTT) propose a radical transparency approach that would enable any Dapp front-end user, even non technical ones, to be fully aware of data provenance, understand implications of transactions before, during and after their execution, and ultimately, be able to trust the code and service at hand.
1 — (Reading Data) Transparency of Data Provenance
A user needs to be able to tell, possibly just by looking at the page, that a certain data point, or content is actually stored in the Blockchain. It is not user friendly to let them be guessing and it isn’t enough to let them assume that “all” data seen is stored in the Blockchain.
This requirement might sound tricky for data-intensive Dapps likes Distributed Exchanges but there are some solutions that will be presented in the examples.
🔑🔑 Principles 🔑🔑
The Dapp front-end should:
➤ 🌀 clarify which data comes from the Blockchain and which doesn’t
➤ 🌀 clarify the address of the contract(s)
➤ 🌀 link all Blockchain data to independent Blockchain explorers
➤ 🌀 clarify which data comes from oracles (∞link > 5.Transparency of code)
How > Examples
- use css to change the color/font/shape to clearly distinguish Blockchain data Obviously try to be consistent across your project and use always the same “Blockchain color”
- use expandable references:
When hovering or clicking on a Blockchain data point, you can provide a contextual expanded tooltip with more information about the datapoint that should make clear where on the Blockchain, in which contracts can the data be found.
- manage styling conflicts with link-icons
if a data point is both a “Blockchain datapoint” and a link to somewhere in your dapp there are two ways to solve the double action:
1- add a link-icon, an icon that follows any “Blockchain data-point” that gives the expandable reference functionality while leaving intact the normal working of the link.
2- open the expandable reference and insert a secondary link inside of it (but consider that this creates more friction because you are asking the user to do 2 actions instead of one).
- use a “Chain-view” mode and/or side panel
For data intensive interfaces like Decentralized Exchanges or market views following the previous suggestions would probably mean styling the majority of the interface, probably adding more confusion. To solve this you can envisage a “Chain-view” button that when hovered or clicked, temporarily styles the data. It’s like putting a filter over the page, a filter that helps the user see which data is a Blockchain datapoint.
Expanding this idea, the “Chain-view” could also be a side panel where many of the functionalities described in the Web3 Design Principles could be hosted. In this case the Chain-View panel could have the aforementioned option to turn on or off the visibility of the Blockchain data points. In the next examples we will see many more uses of the Chain-View panel.
- Clearly show which links open the external Blockchain explorer
If a link is going to send the user to another page it is better to control the flow of the user on the page by:
1 — adding a clarifying button that states what is going to happen: ie “open in Etherscan”
2 — ad a link-icon for independent block explorers and use it consistently across your UI
2 — (Writing Data) Transparency of Transactions
The user needs to be aware that data will be written to the Blockchain, and especially when it entails the exchange of an economic value (cryptocurrencies or tokens). Even though Wallets do warn the user about this intent, the Dapp should clarify this before launching the transaction request to the wallet.
Types of Transactions
There are different types of transactions that can happen when interacting with the Blockchain and each have different consequences.
The user should be able to differentiate between them through the information provided by the UI in different phases, even before launching the transaction.
2.1 - Value Transfers
— 2.1.1 - ETH
— 2.1.2 - Tokens
2.2 - Function calls
— 2.2.1 - contract methods with value implications
— 2.2.2 - contract methods without value transfers
2.3 - Factories: contract generating functions
Transaction data and costs
Transactions usually have a “payload”, some data attached, for example passed to the contract methods, and that is usually used to write or calculate what to write in the Blockchain.
Moreover writing data to the Blockchain usually has a cost, a “gas fee” to pay for the transaction.
The user should understand these two informations and be made aware of their content.
🔑🔑 Principles 🔑🔑
The Dapp front-end should:
➤ 🌀 (Permanence) clarify actions that are irreversible (all writing Txs)
➤ 🌀 (Value) clarify actions that involve money or value
➤ 🌀 (Privacy) clarify actions that could potentially lead to user identification
This is one of the hardest principles to implement as potentially any writing data can help to identify the user (until ZTKSnarks), and as smart-contract and web3 developers we can be unaware of the current and future sophistication of forensic tools, which are also usually closed source solutions. Just take into account this principle if privacy is a main feature of your Dapp, and use it to guide the design choices of when to clarify what actions are potential risks for your privacy seeking users.
➤ 🌀 (Factory) clarify actions that generate new contracts in the users name
This principle is to be applied only to Dapps that help the user create contracts with their address as the creator of the message. Apply this especially if it’s on MainNet.
Guidelines for all transactions:
➤ 🌀 clarify and confirm in advance the new future State
➤ 🌀 show the data that is being used for a transaction in a human readable format and in the way the Smart Contract requires it (∞link 5.Transparency of Code)
➤ 🌀 clarify suggested values for gas price and how to overwrite the Tx (∞link 9.Gas Price and Transaction Reversals)
➤ 🌀 manage Transaction wait time (∞link > 6.Time/Wait Management)
➤ 🌀 After the transaction is recorded show a relevant summary of the transaction to the user and how she can access the history (∞link 4.User Interaction History)
➤ 🌀 possibly, clarify what actions are NOT transactions and hence safe
How > examples
- use css to indicate all irreversible actions
maybe use a warning/highlight colour like red - add a tiny written warnings along with the button
ie: attention irreversible action ahead > learn more - use double confirmation:
open a pop-up or toast, after the user presses the button and before calling the wallet/MetaMask, where you can inform the user of all the implications and ask for a confirmation.
Also offer the user to:
— cancel the action
— never show these pop-ups again (because she is an expert user) and when doing so tell the user that she could eventually reactivate the feature in the Chain-View side panel. - clarify & anticipate future expected steps
either with tiny written descriptions, label subtitles or with wizard like flows which have more steps to accomplish an action.
In the case of wizards:
— clearly show the user the number and title of the next steps
— allow the user to inspect the future screens to understand what is going on and what is going to happen (∞link 8.Newbie mode), although you should also grey out the functionality to not confuse the fact that she can have a sneak peak preview with the actual action. - Add options to the Chain-View side panel
The side panel could be the place for many of these warnings as well as offering an inspector into the transactions, defining
— the type of transaction
— the data associated with the transaction
— the gas costs
— all other relevant information (∞link 5.Transparency of Code)
3 — (Pushed Data) Transparency of Smart Contract Events
Events are the notifications of the Web3 era
(Ethereum) Smart-Contracts can emit Events which are used to both store logs in the Blockchain and to reactively inform Dapps front-ends via Javascript that something has happened.
It is important to understand that Events
— can have parameters, information added to the logs
— are permanently stored in the Blockchain and therefore can be searched for
Events are normally used by developers for various things such as signaling when a certain condition has been fulfilled or when a certain action has happened: a new user has become a token holder, a deposit has been made, or a data has been received from an Oracle, and many more.
The fact that Events can be searched is immensely useful to log the behavior of one specific Dapp, and understand what happened and when, across the thousands or millions of blocks since the Dapp creation.
To better understand why this is so important let me quickly tell you a personal story:
When the Dao was hacked in 2016, I had the chance to collaborate with the group solving one part of the big problem: understanding who was owed what amount of Ether from the ExtraBalance account.
When users bought Dao Tokens during the ICO, according to the fee schedule, different amounts of ether would go into the ExtraBalance.
Two of the group’s problem solvers, Nick Johnson and Bokky Poobah, used the “CreatedToken” Event, to trace all transactions related to the DAO ICO, while I went the “hard route” imagining a situation where Events had not been implemented, and developed a deterministic parser for the Blockchain, a forensic tool very useful in case of malicious or badly planned smart-contracts. I did this also because there wasn’t an Event like “ReceivedByExtraBalance” to pinpoint that part of the transaction.
Here is where it gets interesting: while their scripts would take a few hours, mine would take around one day or more; that is because I had to go through (re-execute) every single transaction in the Blockchain, while they had already access to the (almost) “right” transactions thanks to the Events logs.
Even so, it took the three of us approximately two months to reconcile the numbers and return the whole balance to the original owners.
What does this have to do with Web3 Design Principles?
Events are used by the developers arbitrarily: they can choose to put or not an Event to signal something important about their Dapp. To give access to the front-end user to the Events in the Smart Contract is being transparent about these choices.
A high degree of useful Events can be a sign of a transparent Smart Contract and Dapp, one that is not afraid to let you know what it does internally. While little to no Events can be a sign of a sloppy or even malicious Smart Contract.
As in the above DAO story, the lack of Events would force a user to develop their own deterministic Blockchain parsers to understand what happens inside, a practically impossible task also because she would need an Archival node.
Moreover, Events are useful for developers to create several types of analytics, notifications and reactive data sources, even independently from the Smart Contract owner/creator. Possibly, this power should be made accessible to the front-end user too without needing to code.
Web3 Postulates:
— it isn’t transparency if it requires a humongous effort to find, see and verify the data
— It isn’t transparency if 99% of users are deterred from wanting to look [2]
🔑🔑 Principles 🔑🔑
a Dapp front-end should:
➤ 🌀 clarify and make accessible to the end user all Events, even if they are just for developer purposes
➤ 🌀 apply relevance: show interrupting messages only for information relevant to the current user, but still allow the user to inspect all Events in a separate Interface
➤ 🌀 allow the user to subscribe-to, unsubscribe-from or temporarily mute certain Events
Events are contract specific so these are simple suggestions of possible implementations.
In addition these ideas are better solved by an external tool, service, a plugin, or library, that doesn’t require the Dapp front-end developers to implement all these “non-core” features into their Dapp.
How > examples
- have a notification center accessible to the user, this is probably a section in the “Chain-View” side panel
- use toasts for important messages
- create filters to select/deselect only certain events or customise notifications based only on certain parameters.
Some filters can be:
— if it contains Ether / tokens
— based on address (mine/the user’s or another address or addresses)
— between timeX and timeY, blockX and blockY
etc.
4 — (History) Accessible and transparent User interaction History
In a future where we interact with hundreds or thousands of Dapps, tokens and probably chains, it makes sense for the user to have a clear history logged of her interactions with each one for future reference.
Wallets already store the history of all transactions, which is a start, but it’s only for one account at a time, and it might therefore be hard to figure out if you interacted across several of them.
Moreover wallets would still be hard unless additional features are built, to filter out only those belonging to a specific Dapp for example.
It is certainly user friendly for a Dapp to help you remember every interaction you did with it, just like you can go back to “purchase history” in any normal app.
It is even more important for Distributed Exchanges and Dapps that could generate hundreds or thousands of transactions for each user.
🔑🔑 Principles 🔑🔑
A Dapp front-end should:
➤ 🌀 provide a history of all transactions from a given address
Allow the user to inspect all interactions ever made with the Smart Contract, probably mainly those of type 2, that write to the Blockchain and therefore modify the state
➤ 🌀 clarify where is the history stored
To provide a history relative to a given user probably means recording her Transaction Hashes on a DB, either on a remote server or better in the user’s local indexDB. This is of course a potential privacy risk, so take note of the privacy principles (∞link 2.Transparency of Transactions) and code transparency principles (∞link 5.Transparency of Code) to clarify to the user where this data is stored.
➤ 🌀 give tools to navigate, search, export, and delete the history cache
How > examples
- similar to the Event notification center, have a User-History tab or dedicated page, probably inside the Chain-View side panel
- allow to filter for different type of transactions (value-eth, value-tokens, function calls, contract generating if pertinent)
- allow to filter by date, from the beginning or between dates
- optional user friendly addition: allow users to add a non-chain note field to the transaction, such as a simple reminder if they want to simply have a human readable and searchable plaintext
- optional: have a search field in case there are hundreds of interactions and if it’s relevant to your Dapp
ie: Decentralised Exchanges might want to add such a feature to allow the user to search for transactions relating only to specific tokens - export: allow user to optionally export the data in csv and explore it through other means, again, especially appropriate in case of large datasets
- delete: allow the user to delete the History from the local cache, but of course clarify that the real history of transactions is not deleted neither from their wallet nor from the Blockchain
- import: it makes sense to add an import option only if the Dapp allows the user to add custom notes to each transaction, otherwise the information can be simply reconstructed from the Blockchain
5 — (Code & Environment) Transparency of Code
If a Dapp can be trusted also means if the code being executed can be trusted.
To be trusted, Dapps should be as transparent as possible about all the aspects of their code.
Web3 Postulates
— for a Dapp to be trusted, it’s code needs to be trusted
— for code to be somewhat trusted, it needs to be transparent, independently executable and verifiable
🔑🔑 Principles 🔑🔑
a Dapp front-end should:
➤ 🌀 Clarify which Blockchain is being used
it seems obvious but in a scenario with proliferating Dapps many can be Blockchain agnostic or run different versions on different chains. Also with Plasma, Polkadot, Cosmos and other scaling solutions it is possible that a Dapp might be tracking transactions in it’s own sub-chain nested deep down a tree of other Plasma chains or other parachains or Cosmos Zones or Hubs. The user should be made aware of where their data is being written and therefore be aware of the technical variables (security, speed, etc) and where to independently verify the data.
➤ 🌀 Clarify the address of the Smart Contract(s) that are being used for read and write operations
and link to independent Blockchain explorers (∞link 1.Transparency of Data Provenance).
➤ 🌀 Clarify which code is open source and where to find it.
➤ 🌀 Clarify where code is being run (local vs Remote Server)
This might be one of the most difficult and cumbersome to implement at a visual level, but if parts need to run on a server have at least a page explaining which parts and why and point to it from any relevant part of the UI.
If the “chain-view” mode seen in the examples of the first principles (∞link 1.Transparency of Data Provenance) has been implemented, that would be a good place where to add these other views.
➤ 🌀 Clarify the web3 provider / Blockchain node (local node, Dapp controlled node, Infura, MetaMask?, or other node)
Why? Because instrumented nodes can record data, like etherscan, and could potentially be a source of privacy risks for the user.
- If possible or relevant allow users to switch to their own node
Although this is already taken care by providers like MetaMask, this principle applies in case your web3 Dapp, for some reason, does broadcasts transactions to specific nodes. Also, transactions going through your own private node can be faster to execute because they avoid the potential queues of public nodes especially during high demand events like crowdsales.
➤ 🌀 Clarify if the Dapp is running on MainNet or on TestNet
Although the web3 provider takes care of this, especially make sure that the user understands that actions are being run on the MainNet if it’s the case (resort also to the other principles in ∞link 2.Transparency of Transactions)
➤ 🌀 Clarify which data read from the chain come from Oracles or has been influenced by oracles
User friendly additions
➤ 🌀 Allow for DIY code execution
allow more advanced users to see the transaction function call before it is sent so that they could verify it and reproduce the action by themselves via command line.
This might seem as an exaggeration because the Dapp front-end is there to simplify the user and hide certain technical matters, but a skeptical/paranoid user would want to verify even single transactions: if the Blockchain is like a distributed database then a user should be able to perform the writing operations independently and the Dapp should still work.
In a radical transparency attitude towards the code, a Dapp that allows this feature is signaling “Don’t Trust. Verify” https://blog.wizsec.jp/2018/02/kleiman-v-craig-wright-bitcoins.html?m=1
➤ 🌀 Clarify the inputs required by the Smart Contract:
Smart Contracts require often big numbers with a lot of zeros, which are unfriendly to the user, especially because it’s very easy to make costly mistakes. It is normal and advisable that the Dapp UI simplifies this process to the user, allowing smaller numbers in a more understandable and less error prone range, like 0 to 100. However, in light of the previous transparency of code principles, it should be made clear to the user where those inputs are being simplified by the UI and clarify, especially in the DIY code inspector, the actual input that the Smart Contract is expecting.
A real case where this was confusing was raised in a discussion with Jorge Izquierdo about the Aragon Voting app . Developers can use the same solution presented for that case and clarify to the user some examples with: the simple number, the scientific notation and the actual input (with all zeros) that the Smart Contract is expecting.
How > examples
- have a “Code Transparency” page always accessible like the Terms of Service or Privacy Policy pages
- link to your github repos in several places
- add to the “chain-view” panel (shown in the examples of chapter 1.Transparency of Data Provenance) a section dedicated to code transparency with
○ information on:
— the Blockchain in use,
— the properties of such Blockchain, especially the average block confirmation time (∞link 6.Time/Wait Management)
— wither it’s MainNet or TestNet
— the web3 provider in use (allow for switching),
— the contract addresses,
— possibly a simplified version of the contract’s ABI with just the methods actually called by the code
— if there is any part of the code being run not-locally (textual explanation and motivation)
— the link to the github repos
○ switches, filters or options to:
— display, with icons and/or by changing colors, which parts / components have data that is processed on a server
— display, with (the “cloud-to-chain” oracle) link-icons and/or by changing colors, which data comes from oracles
— if relevant, change the web3 provider
— a preview of transactions being called with the function calls that could be copied and executed on the command line
with notes on the inputs if relevant.
General Web3 UX Principles
The following principles don’t directly relate to the Transparency and Trustless properties any more and are rather aiming at solving a set of other UX problems that arise from the general use and implementation of Distributed Applications based on the Blockchain.
6 — Time/Wait Management
Until the scalability problems are solved, Transactions are asynchronous and according to the underlying Blockchain and the current network congestion, could take a long time to process and be fully confirmed.
A well designed Dapp needs to clarify these informations and manage the user’s wait until her action is confirmed.
🔑🔑 Principles 🔑🔑
a Dapp front-end should:
➤ 🌀 (Manage the user’s expectation) Clarify at every transaction the average block confirmation time of the underlying Blockchain and the current network congestion
➤ 🌀 (Manage the waiting time) Show liveness indicators during waiting time
How > Examples
As a sequence of UX events a Dapp should
- explain how gas choices will affect their waiting time (∞link.9 Gas Prices and TXs Reversal)
- show warning about chain specific times
- Show a progress or waiting icon until it’s not resolved
- If things are taking longer than normal, show a feedback and potential causes and/or solutions
ie: “ it’s taking longer than expected. The network is currently congested.
Here are your options:
-> Wait X seconds/minutes more
-> add more gas to speed up the transaction
-> get notified when done - Inform that in any case you will notify the user of the successful execution
- Once the operation is done, inform of the successful execution with a report of the data (ie. the Transaction Hash) that they can independently verify
7 — Human Readable Hashes Format
Until Name Registries are widely adopted, and even then, we have to deal with the difficulty of long Addresses and Transaction Hashes.
These are just some ideas on how to make them more human readable, while at the same time maintaining the transparency of the full information.
🔑🔑 Principles 🔑🔑
Dapps front-end should:
⚠️ 🚧 Temporary Update 2018–07–11 There is currently a debate on the security of some of these principles. Come back in a couple of days for a better and more secure version 🚧 ⚠️
➤ 🌀 show a compact versions of the hashes but always show the initial and end parts
ie: 0xABCD…EFGHbeware however that this might contain security issues, because vanity address generators can produce sequences of 8 characters in ≈1 week,
➤ 🌀 ̵i̵f̵ ̵y̵o̵u̵ ̵n̵e̵e̵d̵ ̵a̵n̵ ̵e̵v̵e̵n̵ ̵s̵h̵o̵r̵t̵e̵r̵ ̵v̵e̵r̵s̵i̵o̵n̵,̵ ̵p̵r̵e̵f̵e̵r̵ ̵t̵h̵e̵ ̵b̵e̵g̵i̵n̵n̵i̵n̵g̵ ̵t̵o̵ ̵t̵h̵e̵ ̵e̵n̵d̵i̵n̵g̵ ̵
̵ ̵i̵e̵ ̵u̵s̵e̵ ̵0̵x̵A̵B̵C̵D̵…̵ ̵r̵a̵t̵h̵e̵r̵ ̵t̵h̵a̵n̵ ̵0̵x̵…̵E̵F̵G̵ (this has security implications as noted by Tom Nash here ) > amended as follows:
➤ 🌀 if you need an even shorter version, prefer the ending to the beginning
ie use 0x…EFGH rather than 0xABCD…
(although it’s more readable and better looking to have the first 4 chars, compared to the 0x…EFGH, there is a security issue because the first 4 characters are more simple to brute-force and generate like is the case of vanity urls, but it’s astronomically difficult to generate the exact match for the last 4 characters)
➤ 🌀 prefer using chunks of 4 letters rather than 3 letters for each part
ie use 0xABCD… rather than 0xABC…
➤ 🌀 always prepend the “0x” to indicate that it’s a hash
➤ 🌀 allow for an optional view where the entire address is visible
➤ 🌀 allow users to easily copy the address
➤ 🌀 where possible use shorthands as titles and the abbreviated addresses as subtitles
➤ 🌀 if possible create a system to allow the user to easily associate a custom human readable name or text to the addresses
these notes should be stored locally on the user’s local computer not on a server (resort to ∞link 5.Transparency of code principles)
If it exists, resort to a known aliases db like the ENS registry or Etherscan for known contracts and addresses.
8 — Permanent Newbie Mode
If we want mass adoption of Distributed Applications it means that we need to enable masses of people without any technical knowledge nor understanding of the Blockchain and its lingo to enter the space.
This is more than other spaces one that requires a bit of education, both for security reasons (handling private keys), but also to fully understand why the properties of the Blockchain are such a revolutionary phenomenon and how Dapps differ from other apps.
Also important is the fact that this space is so wonderfully faceted that often requires new mental models and a multidisciplinary understanding: the Internet of Value is creating thousands of tokenized ecosystems influenced by market dynamics, which are normally studied in Economics, Finance and Game Theory; It is very unlikely that the masses will be versed or have ever had exposure to these disciplines.
Therefore Distributed Applications should make an effort to educate new and established user to all aspects of their working.
Most of the previous principles have a newbie user in mind but there are a couple more things that developers should consider.
🔑🔑 Principles 🔑🔑
A Dapp front-end should:
➤ 🌀 Weave in educational information with the normal interaction
The main task for Dapp Designer has been excellently summarized by Nick Neuman: “A good end-user application will bake education into the product experience. This means explaining in a concise and interesting way why a user is doing something while she is doing it, and building the product so it’s very hard for the user to do something unsafe.”
➤ 🌀 Provide 2 or more levels of educational content: Blockchain basics and Dapp specific lingo
This is not a principle just for our time in which newbies are coming on board, it would be a good practice for all apps, especially those that have an internal or contextual lingo or unique mechanism, to add another educational layer: ie. if you are building a token fund manager, don’t assume your users know finance and what each term means; instead educate them both to the basics of Blockchain and the basics of finance, at the very least to understand the words you are using.
➤ 🌀 Minimize and increase progressively the amount of new things and concepts that the user needs to learn
Blockchain projects, in spite of the tokenized incentives to adoption, will still have to face the normal friction and churn that any Software service experiences: users will choose simpler alternatives especially if a Dapp asks too much of them. Therefore Dapps, in delivering their educational content to newcomers, should try to minimize the use of new words and concepts, especially in the pages for the generic public (ie the home page) and progressively show more learnings in pages for engaged users (ie User dashboards). This can be achieved also by using simpler language, avoiding lingo, and using analogies to explain complex new information with knowledge the user might already be familiar with. As an example see how Spankchain created the concept of a card to avoid having to explain payment channels.
➤ 🌀 If possible or relevant, accelerate learning providing the “expert’s interpretation”
Demystify the meanings of your Dapps functions, how they interact and how an expert would think about the effects.
What would an expert know about a certain specific thing? How would they interpret the data? How would they act upon it? What choices would they make?
The answers to those questions could be weaved in as suggestions in the Dapp UI, if they are relevant.
Examples go from anticipating good gas pricing (∞link 9.Gas Prices) to indicating wither it’s a good or bad moment to exchange a certain token (just an example).
➤ 🌀 Don’t loose context
try to weave in the snippets within the interface, with temporary pop-ups that can be easily dismissed that then could open more detailed information in another tab. When learning, allow the user to learn quickly and “in place”, without changing page and loosing track of what they where doing.
How > examples
- add small subtitles for commands all over the place (and refer to other principles to anticipate what transactions are going to do ∞link 2.Transparency of Transactions)
- learn mode setting
add to the “chain-view” or other parts of the UI, a switch (a “universal question mark” button) that can be turned on and off and enables or disables learning features - Glossary pop-up
When using lingo that is available in a dictionary, display a link-icon, an icon after the word, that if clicked or rolled over, displays a contextual pop-up with the specified information
In some cases, the pop-up should also offer the opportunity to “know more”, which will open another tab or a sidebar in the “chain-view” opened in the glossary tab. - Glossary page
in the chain-view or in another page entirely the Dapp should provide a page with all the terms, Blockchain and Dapp specific, that are being used in the Dapp itself or that are needed to understand its mechanics. This page should be redirected from the glossary pop-up, not linked directly. - in any wizard, it would be savvy to enable fast forwarding to the next steps so you can see what is coming, although all their layouts should be greyed out and disabled until you complete the previous steps. This is a good principle for any ui, not only of Dapps.
9 — Gas Prices and Transaction reversals
Gas is one of the most confusing things for newbies. Even if the name is telling, it is difficult to imagine the cost of computation for services you’ve always had for basically free.
What’s more, when users encounter gas for the first time, they don’t know how to price it nor, therefore what a good choice for gas price would be.
Even if nowadays in practically all cases the gas is handled by wallets who emit the transaction, this principle is still valid, both for wallet designers and for all those who will ever require or ask the users to choose a gas price.
luckily for developers there are tools like the Ethereum Gas Station which offers a convenient API.
🔑🔑 Principles 🔑🔑
Dapps front-end should:
➤ 🌀 Clarify what is Gas and Gas price
(just like with any other lingo ∞link 8.Newbie mode)
➤ 🌀 Suggest a good range for gas price and clarify time approximations for the upper and lower range limits
these are functions of the current congestion of the network, so the optimal solution would be to query the current Ethereum Gas Station API https://ethgasstation.info/json/ethgasAPI.json to suggest these range bounds.
It’s important to clarify to the user that this is a time based suggestion and that the proposed values could change in the future.
➤ 🌀 possibly show gas values converted also to FIAT
➤ 🌀 Allow for Transaction reversal: in case the user has sent a TXs with low gas price it should be made clear to the user
(∞link to 6.Time/Wait Management)
- that the tx can’t be cancelled once it has been launched
- that the only solution is to broadcast another tx with the same nonce and a higher gas price
> therefore offer the option to automatically recover the tx nonce and to send it with a higher gasprice.
DDP Decentralization Design Principles
Decentralization is a new powerful form of globalization.
One that, for the first time, is potentially led by masses of self-sovereign individuals coalescing around borderless ideas, self-managing organizations and distributed market systems.
These Design Principles only want to get the conversation started in both thinking how to make the user feel part of a community and of something more aspirationally bigger than themselves.
They are just a hint for developers to start thinking holistically about the function of their Dapps, and the new UX requirements that emerge, in the larger context of the distributed societies we are creating.
10 - Sense of Community
Dapps are different than apps because they are natively distributed: even if some are services targeted to the individual and whose interaction is a solitary experience, they are still made for, and often by, a large group of people all over the world.
The sense of belonging to a community is more important in these Dapps as users will need to bond to a decentralized brand and product.
That doesn’t mean to bake in the Dapp a social network, although some might benefit from tighter integration with the community chat chosen by the project.
Needless to say these ideas are pretty important for DAOs.
Consider the following just as some generic suggestions within the more loosely interpretable objective of making users feel part of something bigger than themselves.
🔑🔑 Principles 🔑🔑
Dapps front-end should:
➤ 🌀 clarify how many other members there are in the community
➤ 🌀 clarify who are the other members (choose appropriate categories)
➤ 🌀 clarify the composition of the community (ie sub-groups and their power over the project)
➤ 🌀 the greater mission of the project (if any) and how their participation contributes to its achievement
How > Examples
- provide a landing dashboard with statistics about unique token holders or number of members of a Dapp or DAO
- adopt the transparency principle and show especially all information that could be derived by the users themselves by analyzing the Blockchain:
— token wealth distribution,
— adoption time graphs,
— token holder since block XX and yyyy-mm-dd
etc - in DAOs consider enriching the information with anything that might be relevant (if available) like:
— kind of members (ie # of breeders vs non-breeders in Crypto Kitties, or # of musicians and # of listeners in Music/ART Dapps like UJO Music, stakers vs non-stakers etc)
— staking distribution statistics
— maybe geographic locations / time zones?,
— maybe sex, ages? (but only if it does makes sense to your community, and if it’s not offensive or detrimental to the adoption of your Dapp) - Obviously search for the categories that are appropriate and relevant to your project: for instance, it’s my personal opinion that in DAOs the sex and ages are not relevant information, even counterproductive to the idea of creating permissionless and unbiased societies, but maybe they are very pertinent in projects like SpankChain.
- maybe allow users to choose their own tags, categories, bio description etc.: each member can have different identities in different projects. This already hints at other principles about identities that will be presented in the future.
11 — Other Future Design Principles
As you might have understood, the previous principle requires some more thoughts around Identities, Reputation and Governance. The first two are universally useful in many community driven apps but they will be fundamental for Token Curated Registries (TCR) and, probably, for many DAOs and other crypto-primitives.
These principles deserve their own analysis and space, and this post is already too long.
In the future I’ll analyze Web3 Design Principles for:
- Identities and Reputation
- Governance
- Wallets
- Exchanges
- ICO & Token Sales Mechanics
- Token Mechanics
Next Steps
It is clear that the requirements of “extreme transparency” proposed in these Web3 Design principles, create quite a burden for Dapp developers who are today more focused on solving many other parts of their projects.
— Bootstrap like library
It is therefore obvious that there should be a standard toolset that developers could plug and play into their Dapps and maybe interface their calls to the web3 library and get, for free, all these transparency services for their users.
I’m imagining something like a Bootstrap like library for the Web3 era (“Chainstrap”? it’s a bit too hard core, right? :P )
— Independent browser plugin
Maybe it’s even advisable that there should be an independent tool that does offer users the advantages of the Web3 Design Principles wither the Dapp creator wants or not; a “transparency enforcer” of sorts, that could allow to identify malicious or sloppy Dapps by their degree of compliancy with some of the principles.
In this case it would probably be appropriate to create a browser plugin that injects its code into the Dapp and provides the chain-view functionality and maybe even a quick certification of the degree of transparency and trustworthiness of the Dapp.
— Custom Services
Moreover in these principles there are many potentials for services, even commercial ones that don’t yet exist today.
Many options. What do you think?
✋ If you are interested in developing any of the above, if you just have thoughts and considerations, 🙏
or if you are a grant offering organization and think that it could fit in your current objectives,
👉 please get in contact b [at] likuidlabs.com, or on twitter @lyricalpolymath 👈
Let’s design and build the future of decentralization together!
NOTES
[1] Other “Blockchain” + Design Articles
Applying the Design Methodology I researched what had already been created on the subject: not much.
- Blockchain Design Principles — Design at IBM
This is by far the best article about the subject. Written by Sarah Baker Mills, former design lead at IBM and today Design Director at Consensys. She distills very well some of the principles that appear in the Web3 Design Principles, although under different names. She talks about data exposure, consistency, feedback, anticipating mistakes, and active guidance. - Blockchain and Design — Hacker Noon
An interview with Matt Storus, Lead Designer at 21.co, about the challenges and some ideas of what designers should do. Unfortunately the interview format doesn’t allow to distill many teachings but he is definitively an interesting read. - The user experience of Blockchain
a generic post to educate designers about the Blockchain and the design challenges. - How can Design help Blockchain — The Spark
a few macro ideas about some things designers in this space should think about - Designing for the Blockchain: launching an ethereum Smart Contract app
A study case around designing a better experience for an investment platform, with some ideas to improve the participation in ICOs
[2] I know these postulates are a phenomenological fallacy, but I use them anyways because they are a useful simplification and make the point: to a non technical user, who is not able to verify the data by herself in an easy way, the information is clearly not transparent. Transparency then becomes a shimmering mirage, a faithful expectation of trust.
