paritytech / governance-ui

Archive

This repo is no longer maintained. Please have a look at its new home https://github.com/polkassembly/governance-ui for updates and contributions.

Polkadot Delegation Dashboard is a PWA - or Progressive Web App - with a focus on efficiency and offline support in the context of Web3.

As a pure web application, it doesn't depend on remote backend to operate but connects to Polkadot nodes. Some data will be fetched to enhance the experience from github.com and polkassembly.io/, although the plan short term is to become fully decentralized.

Use

Register as a delegate

Anyone can register themselves as a delegate.

To add a new delegate, edit this file and push a pull request. Once approved, changes will be transparently picked up and made available to anyone in the application.

The following table outlines the structure of a delegate entry:

Element	Key	Required	Notes
Delegate Name	name	Yes	The chosen name of the delegate.
Delegate Address	address	Yes	The chain address of the delegate.
Manifesto	manifesto	Yes	A description of your goals as a delegate. Supports markdown.

Build

The full website can be started using yarn build. PUBLIC_URL can be set to the final root URL for the considered deplyment environment if required.

Development

A local dev environment can be started using yarn dev.

Testing

Unit tests can be run via yarn test:unit.

Run end-to-end tests via the following steps:

# Setup
yarn
npx playwright install

# Run webapp in a dedicated tab
yarn dev

cd test/

# Run chain in a dedicated tab
yarn zombienet:native

# Launch tests
URL=http://127.0.0.1:1234/?rpc=ws://127.0.0.1:9984 yarn test:e2e

Using containers

You may build a container using:

./scripts/build-container.sh

then run your container with:

podman run --d -p 8080:80 localhost/polkadot-delegation-dashboard

and access the Delegation Dashboard at http://localhost:8080/

governance-ui's Issues

Implement generic error components

It should be possible to show a error message from anywhere.
Should we consider blocking/non-blocking errors? Per component?

Resources

API

• https://realfiction.net/2019/03/11/use-reacts-context-to-display-an-error-message-somewhere-else
• https://www.yld.io/blog/global-notifications-with-reacts-context-api/

UI

• https://chakra-ui.com/docs/components/alert/usage
• https://blog.logrocket.com/ui-design-best-practices-loading-error-empty-state-react/
• https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f

Implement responsive layout

Implement e2e integration tests

As part of CI, it would be great to perform e2e tests on the frontend to validate correct behaviors. Those tests (the non-destructive subset) could be leveraged to test staging and production environment too.

Depends on #4

Libraries

• https://github.com/microsoft/playwright

Create per track template

Open Gov defines a number of tracks. A custom UI should be used to display relevant details accordingly.

Elements to consider

• referendum state (only show ongoing?)
• origin (identicon?)
• track details (name, decision, lifecycle, curves)
• proposal details
• enactment/submission/decision details and lifecycle
• tally details
• alarm details

Historical elements (initiator details, voters, delegates, ..) are not considered yet.

i18n

• https://react.i18next.com/
• https://lokalise.com/blog/react-i18n-intl/

Consolidate data into reducer

• migrate wallets/accounts
• extract restore in a preliminary step
• make internal start** sync with reducer creation
• migrate permissions (using listener)
• introduce settings (and migrate timeouts, include query params/ENV accesses)
• migrate fetch chain state to subs
• abstract away chain access

Allow pool operator to react to pool users mistakes

As a pool operator, I want a simple action to request funds accidentally sent to pools to be transferred back to the user account

Deploy on production environment

DApp should be deployed on a production ready and sized to support the planned workload

• serve from proper domain
• deploy on dedicated infrastructure
• use dedicated RPC node
• enable analytics
• perform e2e tests

Add Active Delegations section

Displayed on top of UI when a user has a bunch of delegation already

Introduce a global React context for modals

Introduce lint/format

Consider using https://rome.tools/ ?

Query Delegation state for connected accounts

We need to query and subscribe to delegation state for the connected accounts, to be able to show proper UX to the user based on the correct state of the delegation.

api.query.convictionVoting.votingFor(accountId,...)

Support substrate-connect

substrate-connect support is currently disabled due to lack of ServiceWorker support.

See paritytech/substrate-connect#1371

UX fixes

Continue btn when no tracks were selected

the button to continue from tracks should depend on whether you've selected tracks or not
if you haven't selected tracks it should either be

• disabled + note saying 'select tracks to continue'
• button saying select delegate first (this way stepper would have to say 1st step isn't done)
• by default all tracks should be selected IMO

Select all only makes sense with the checkbox if it has additional functionality

• idea is a copy of gmail select all dropdown (eg. select all / select active / select all technical tracks / etc.)
• if we don't add extra functionality now, it might make sense to have a simple btn/link that say select all/deselect all

Hints

we could reuse the modal to display hints

• next to section titles (info on tracks, info on delegates)
• where else

Delegate cards have to be expandable to display longer text with extra things like matrix handle, website (maybe arbitrary key/value pair?)

• in full delegate list its easy, they can just open within the columns (they have to be columns x rows, instead of row x columns)
• in recommended delegates list it won't work b/c it won't fit - should we open in modal? eventually in full page if we have more info? straight to full page now?

Add error notification UX

We need to have an error notification for scenarios where something goes wrong during the delegation process.
Mainly there can be two types of errors:

• Validation error: This happens when there is an issue in the modal when the delegation happens. (e.g. delegation is not possible because the user does not have free balance to delegate?!)
• Chain submission error: while submitting the transaction for some reason fails (This can be shown as an overlay notification box?)

Migrate UI to shared components

Also relates to #123

Validate copy content

Make sure all text content is provided (i.e. no lorem ipsum) and validated.

Allow validators to react to a slash

As a validator, I want a simple action to respond to a slash

Investigate Preact usage

Preact is a leaner/lighter implementation of React. Figure out if it is doable to use it, and do the migration if yes.

Migrate existing common components to shared components

• button
• card
• loading
• modal
• navbar
• spacer
• text

Add delegation calls to the Modal

Need to add delegation calls to the Delegate modal to have a complete e2e delegation flow.
related #207

Tracks should be populated with ongoing referenda

Display:

• title
• aye/naye
• links to relevant platforms

Provide a mocked env

During development it is useful to be able to mock third-parties so that stub answers can be returned.

Playwright mocking

• https://playwright.dev/docs/mock

Chains

• https://github.com/polkadot-js/api/blob/master/packages/rpc-provider/src/mock/mockHttp.ts

Polkassembly

• https://blog.bitsrc.io/how-to-mock-your-graphql-api-f53a6a6e676f
• https://www.apollographql.com/docs/apollo-server/testing/mocking/
• https://github.com/mswjs/msw
• https://miragejs.com/

IndexedDB

• https://github.com/dumbmatter/fakeIndexedDB
• https://dev.to/andyhaskell/testing-your-indexeddb-code-with-jest-2o17

ServiceWorker

• https://medium.com/dev-channel/testing-service-workers-318d7b016b19

Allow user to provide any address as delegate

Migrate accounts/wallets to reducer

Investigate e2e improvements

• https://playwright.dev/docs/ci
• https://playwright.dev/docs/evaluating
• https://playwright.dev/docs/trace-viewer
• https://substrate.stackexchange.com/questions/2523/zombienet-how-to-build-a-docker-image-with-my-parachain-and-adder-collator-bina
• https://substrate.stackexchange.com/questions/2856/zombienet-substrate-parachain-template-how-to-write-the-dockerfile
• https://yonatankra.com/2-ways-to-use-your-docker-image-in-github-actions/
• https://docs.github.com/en/actions/using-containerized-services/about-service-containers

Finalize delegate label list

Delegate will get assigned labels depending on their conditions:

• nominator (if this address nominates a validator)
• fellow (if this address is a fellow)
• validator (if this address is a validator address)

Most necessary hints

Design tooltip/modal for most necessary hints

Query balance for connected account

We need to query the account balance for the connected account to be able to show the user the balance they can delegate,
when they submit the delegation tx.

If the user does not have enough balance to delegate the modal should present an alert message and the delegate button should be disabled.

Investigate reducer history

• https://redux.js.org/usage/implementing-undo-history
• https://github.com/marcolink/history-reducer
• https://github.com/jakub-zawislak/react-use-history-reducer
• https://dev.to/sgolovine/persisting-usereducer-with-a-custom-react-hook-1j27
• https://github.com/rt2zz/redux-persist

Implement application monitoring

Allow dev to have access to a timeline of internal events

• https://developer.mozilla.org/en-US/docs/Web/API/Performance
• https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEventTiming
• https://github.com/open-telemetry/opentelemetry-js
• https://opentelemetry.io/docs/instrumentation/js/getting-started/browser/
• https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/opentelemetry-web
• https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-web
• https://rleiwang.medium.com/instrument-web-app-with-opentelemetry-using-web-worker-212161a299e9
• https://www.honeycomb.io/blog/opentelemetry-browser-instrumentation
• https://cloud.google.com/community/tutorials/web-instrumentation
• https://signoz.io/blog/opentelemetry-vs-jaeger/
• https://zipkin.io/
• https://github.com/jaegertracing/jaeger-ui

Allow to connect to any chain

Drop per network type augmentation, get element type at runtime.
Also drop fixed network typings.

General reducer improvements

• define how to store UI transient states
• keep track of history via delta persistency

Resources

• https://evilmartians.com/chronicles/how-to-avoid-tricky-async-state-manager-pitfalls-react
• https://redux.js.org/faq/organizing-state
• https://stackoverflow.com/questions/60290678/redux-domain-data-and-app-state-vs-ui-state
• https://redux.js.org/tutorials/fundamentals/part-5-ui-react

Add delegate data

We need to pull and aggregate some information regarding delegates to present them to the users.
The below schema is based what is going to be presented in the delegate Cards.

{
    account: {
      name:'can be pulled from identity pallet if available',
      address:'account address'
    },
    roles: ['nominator', 'fellow', 'validator', ...],
    bio: <since currently there is no profile we can have some logic to autogenerate a paragraph based on the delegates information to be used as their bio> >
    stats: [
      { title: 'Most active track', value: 'Staking admin' },
      { title: 'Participation', value: '75.71%' },
      { title: 'Representing', value: '135 addresses' },
      { title: 'DOT', value: '24k DOT' },
    ],
  }

I believe these are reasonable to present to the users in the first iteration.

Deploy branches on netlify

• https://github.com/jsmrcaga/action-netlify-deploy
• https://github.com/nwtgck/actions-netlify
• https://github.com/netlify/actions/tree/master/build
• https://www.netlify.com/products/build/

Allow to deploy local dev chain

During development it is useful to be able to control the underlying relay chain. It should be easy to start a local chain, have the UI connected to it, and play with the app.

Controlled chain

• https://github.com/paritytech/zombienet (video)
• https://github.com/PureStake/moonbeam-tools/tree/main/src/libs/helpers/state-manipulator
• https://github.com/open-web3-stack/parachain-launch
• https://github.com/AcalaNetwork/chopsticks (video)
• https://github.com/centrifuge/fudge (video)

Implement Delegation tx

Implement the delegation transaction to let the user submit delegation tx.

for the MVP we will only let them submit the default conviction (0.01x), but this can be handled by the UX and the implementation should accept parameters as we might extend UX in future iterations.

Improve graphQL usage

Use multiple ids at once:

• https://stackoverflow.com/questions/66726617/apollo-graphql-multiple-id-variables-in-one-query
• https://discuss.dgraph.io/t/cannot-query-by-multiple-ids-on-graphql/11338

Fix `@polkadot-onboard/injected-wallets` export

@polkadot-onboard/injected-wallets disable global tree-shaking in parcel via the following message:

@parcel/transformer-js: Unknown usage of CommonJS `exports` object. This causes tree shaking to be disabled.

  /Users/julien/Documents/Projects/jeluard/swipealot/node_modules/@polkadot-onboard/injected-wallets/dist/injectedWallets.js:1:18
  > 1 | var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
  >   |                  ^
    2 |     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
    3 |     return new (P || (P = Promise))(function (resolve, reject) {

  📝 Learn more: https://parceljs.org/features/scope-hoisting/#commonjs

Make sure this is not the case. While there are a couple of others lib (bn.js) that have the same behavior, this would be a step in the right direction.

Provide an offline first foundation

Add Footer UI element

Move running zombienet instance in e2e workflow from native to podman provider

This is dependent on paritytech/zombienet#704
After zombinet support static ports for podman provider we should move the zombienet instance in the e2e test workflow from native provider to podman which is more reliable.

Improve stalled rpc provider detection

See polkadot-js/api#5408 and polkadot-js/api#5467

Implement voting

Once a user went through all referendum it will be presented with a list summarizing their choice (here).

It should now be possible for the user to click on a button to sign-and-send a batch of transactions of all the votes.

Note that at the moment there is no account management implemented. polkadot-wallet-onboard might be considered for this.

• add wallet selection support
• implement batch voting

Add UI element allowing to gather feedback

Users should be able to provide feedback from the app, by clicking on a link/button that would redirect to a 3rd party website.

https://polkadot-staking-dashboard.canny.io/feature-requests

Augment delegate card with current delegation

As shown in pink element in the mockups.

Current delegation status is available in the reducer state as chain.allVotings.

Enable tree shaking

Tree shaking is currently disabled due to an issue with bn.js

@parcel/transformer-js: Unknown usage of CommonJS `module` object. This causes the module to be wrapped, and tree shaking to be disabled.

  /Users/julien/Documents/Projects/jeluard/swipealot/node_modules/bn.js/lib/bn.js:3547:37
    3546 |   };
  > 3547 | })(typeof module === 'undefined' || module, this);
  >      |                                     ^^^^^^
    3548 | 

  📝 Learn more: https://parceljs.org/features/scope-hoisting/#commonjs

@parcel/transformer-js: Unknown usage of CommonJS `exports` object. This causes tree shaking to be disabled.

  /Users/julien/Documents/Projects/jeluard/swipealot/node_modules/bn.js/lib/bn.js:3547:45
    3546 |   };
  > 3547 | })(typeof module === 'undefined' || module, this);
  >      |                                             ^^^^
    3548 | 

  📝 Learn more: https://parceljs.org/features/scope-hoisting/#commonjs

Add monitoring

• https://www.simpleanalytics.com/fr

Move to open gov

Data source should be open gov referendum.

Allow to schedule vote submission

It might be useful to schedule vote submission (e.g. if offline, to hide linked accounts).

• https://developer.mozilla.org/en-US/docs/Web/API/Background_Synchronization_API