substrate-developer-hub / substrate-front-end-template

A Polkadot.js API + React based template for building Substrate Front Ends

(Old) Substrate Developer Hub (ARCHIVED)

THIS SITE IS ARCHIVED.

• New site: https://docs.substrate.io/
• Source available: https://github.com/substrate-developer-hub/substrate-docs/

This repository houses documentation for the Substrate blockchain framework.

The docs are written in markdown, processed by Docusaurus, and hosted at the Substrate Developer Hub.

Contributing

Thank you for your interest in contributing to the Developer Hub and to the larger Substrate community! Please review our contributor guidelines prior to any contribution. If you have any further questions, don't hesitate to reach out on our substrate technical community channel.

Directory Structure

This repository is structured as a Docusaurus project with the markdown files organized in the /docs directory. Images and other assets are in the /docs/assets/ directory. The /website directory is a Yarn Docusaurus project with many helpful scripts (e.g. yarn build, yarn start) for working with this codebase.  In the /website directory you will find sidebars.json and siteConfig.js, which are important Docusaurus files. You will find the source code for some top-level pages in /website/pages/en. Follow our contribution guidelines.

Adding a new document

To add a new markdown document:

• Create your markdown document in a suitable directory inside /docs.
• If you have images in your document, put them in the /docs/assets/ directory.
• Documentation should follow our contribution guidelines.
• If you want your document to appear in the sidebar, add its reference in the /website/sidebar.json file under the   corresponding section.

Rename an existing document

To rename an existing document:

• Change the name or path of the document.
• After the change has been merged, go to the Crowdin project,   make sure the translation is already migrated to the new file automatically for all the target languages.
• Then go to Crowdin project settings, remove the   old source file in Files tab.
• If you don't have access to the Crowdin project, please send email to [email protected] with the   file information you want to remove.

Local Testing

• cd into the /website directory.
• Execute yarn install and then yarn start.

The Substrate Developer Hub website should open in a browser window.

Link Checker

Once the website is running, you should use the included Yarn script (yarn check-links) to ensure that your changes do not introduce any broken links and to check for any links that have broken since the last time the check was executed. Please ensure all links are fixed before submitting any changes; if you have questions about broken links that you did not introduce, please create an Issue.

Once you are done with your changes, feel free to submit a PR.

Updates

There is a helper script that can be used to update substrate.dev/rustdocs links in the docs/knowledgebase directory.

# This examples demonstrates updating links from v2.0.0-rc3 to v2.0.0-rc4
OLD_VERSION=v2.0.0-rc3 NEW_VERSION=v2.0.0-rc4 ./scripts/update-kb-rustdocs

Production Deployment

Our production site is at substrate.dev. To deploy to production, merge your update into the source branch. This triggers the CI to build the website AND also pull in multilingual translation from our Crowdin project. The final built static site is then pushed to the master branch and hosted on GitHub Pages.

Staging Deployment

We have a staging deployment at devhub-maindocs.herokuapp.com, which is hosted on Heroku. Please check with the devhub team for the username and password to access the staging site.

To deploy to staging, you could push to the staging-source branch in the repository. This will trigger the CI to build the website, pull in multilingual translations from crowdin, and have the final built static site being pushed to staging branch. This in turn triggers Heroku to pick up the latest commit from staging branch and deploy to the staging site.

License

Substrate documentation is licenced under the Apache 2 license.

substrate-front-end-template's Issues

Define scope of UI template

Related to my comment #22 (comment)

It would be helpful to define what is and is not in scope for this template. Is it
1 an example and starting point for writing dapp-specific UIs
2 a stripped down version of Apps?
3 a replacement for bonds ui?
4 other?

So far I've thought of it as 1 and 3 but not 2.

Once we have consensus about what this template is for, we should add it to the readme to guide users in understanding what they can do with it and to guide contributors in knowing which features are in scope.

Here's my first attempt:

The UI template is an example and starting point for creating user interfaces for Substrate-based dApps. It uses react and polkadot-api as its primary dependencies. It does not strive to be a general purpose blockchain interaction tool, that's what apps is for.

Explore/Implement a module to submit Substrate RPC Call

Components support modules with non-standard names

Currently our components hard-code methods like api.tx.Balances. The module name comes from the construct_runtime! macro and need not be named in the standard way. Each component should take an optional prop to specify the names of the module (or modules) that it depends on.

can't deploy to gh pages?

I'm trying to deploy this template to GH pages:

cloned it:
https://github.com/encointer/explorer

set up GH actions that should deploy it to
https://encointer.github.io/explorer/

deployment action works but I get an empty page although running locally with yarn start works.
any idea?

Integrate Substrate UI components

https://github.com/paritytech/substrate-light-ui

Utility Component: Handle account balances

From: #38

Create a "utility" component which handles account balances.

Given a large number (in BN/String/Number) format, automatically fix the value to the correct decimal point configuration, and handle making the large numbers more readable.

I imagine an API like this:

<PrettyBalance>10000000000000</PrettyBalance>

output (default decimal is 8):
100 Kilo Units

-or-

100,000 Units

<PrettyBalance decimal=12 unit="DOTs">10000000000000</PrettyBalance>

output:
10 DOTs

This component and others like it can be saved in a folder named "utilities" or something.

Tx button transformParams logic should not process null value

Change this:

    const paramVal = inputParams.map(inputParam => {
      if (typeof inputParam === 'object' && typeof inputParam.value === 'string') {
        return inputParam.value.trim();
      } else if (typeof inputParam === 'string') {
        return inputParam.trim();
      }
    return inputParam;
  });

to this:

    const paramVal = inputParams.map(inputParam => {
      if (inputParam !== null && typeof inputParam === 'object' && typeof inputParam.value === 'string') {
        return inputParam.value.trim();
      } else if (inputParam !== null && typeof inputParam === 'string') {
        return inputParam.trim();
      }
      return inputParam;
    });

"Use Extension" Component

Maybe a friendly component which can detect if the user has the Polkadot JS Extension installed and in use, and if not, to install it at a link.

`yarn start` fails when using VS Code editor

Peer-dependency eslint@6 has a bug that causes react-scripts to fail when run in the VS Code text editor. See: microsoft/vscode-eslint#750

It would be helpful to (at minimum) add a warning about this in the README; it took me a nice bit of bug hunting to figure this out and definitely made getting started with Substrate more difficult than it should have been.

Allow decorating RPC information in the UI config

TxButton Should Check Sudo User

It makes sense if TxButton is set to "sudo" that it checks the AccountPair being passed to it is indeed the sudo user.

Since TxButton is component is reused in other components, and likely reused in components people create, it makes sense to add a bit more complexity/safety around it.

Chain State Component

We should create a component equivalent to the "Chain State" tab in the Polkadot JS Apps

Update to use Bootstrap instead of Semantic UI

I have a feeling that Semantic UI may be a slightly higher learning curve than Bootstrap.

(this could be a false assumption)

Anecdotally, I think everyone knows bootstrap, and it is the de-facto starting point for making any simple UI. I think we want to minimize ALL possible points of friction for a new developer, so it may make sense to use Bootstrap here instead.

I took a look into this, and it did not appear that react-boostrap could easily generate a table from an object, which was the main problem transitioning, but I did not really look into it.

This issue can for the time being be used as a conversation about this assumption.

Wallet Integration with Frontend template

I would like to see, wallet integration with the front end template.

Unsubscription of transaction events in pallet interactor

Publishing substrate-lib components as a separate npm package?

After:

1. completing a socket selection function/component,
2. putting AccountSelector component into src/substrate-lib/components,
3. adding a few test cases (not comprehensive),
4. adding an examples folder, copying some of current component in src/ as demo on how to use it

I would like to publish this as a separate npm package. So in future app developers don't have to keep forking from our front-end template, but can just use it as yarn add .... Also address Julien issue that need to keep a separate fork after adding his own functionalities.

What's your thought?

Probably called substrate-react.

Better error handling on invalid custom type

Front end can display an error message showing invalid custom type, as opposed to hanging on the loading screen.

New Production Endpoint Needed

The front end template uses wss://dev-node.substrate.dev:9944 as the production endpoint for its live deployment:

https://substrate.dev/substrate-front-end-template/

@Tbaut was the one who set up this special dev node, but it has not been updated to latest substrate for a while AFAICT.

So we need to update this node or pick a new endpoint like Polkadot/Westend/Kusama

Custom Types Component

Related to #16 and 800bd2b

We should see if we can avoid the UI vomiting if there are missing types, and allow users to specify new types right in the UI.

Allow changing the socket url after the app is started

Taking rpc parameter to specify connecting substrate socket

If implement this feature, have a flag to control whether to enable this behavior.

Create Test Suite

We should create a test suite for the Substrate UI Template

Users Component

Component for generating, adding, and removing new users to the UI

Fix the github security warning in repo page

Error calling extrinsics that do not require any arguments

If it's connect to a Substrate kitties node and then try call the createKitty Extrinsic, which doesn't require any arguments, and then click "Call" it returns the following error in TxButton because the params value is an array containing an empty string [""]

Unhandled Rejection (Error): Extrinsic substratekitties.createKitty expects 0 arguments, got 1.

  32 | setStatus("Sending...");
  33 | 
  34 | // Check if this transaction needs sudo
> 35 | let txExecute = sudo ? tx.sudo(...params) : tx(...params);
     | ^  36 | 
  37 | txExecute.signAndSend(fromParam, ({ status }) => {
  38 |   status.isFinalized ?

Refresh the api connection when reconnect to a Substrate node

Block Info Component

• Block Hash
• Parent Hash
• Extrinsics
• ?

Deploy with Github Pages

We should make this UI deploy with GitHub pages

:)

Add module checks for all components

Check the module being used by a component actually exists before rendering a component or making calls, else it will crash the site.

The tutorial of front-end is gone

Why the tutorial about front-end is gone and also the docs?

react-scripts: not found

git clone https://github.com/substrate-developer-hub/substrate-front-end-template.git
cd substrate-front-end-template/
yarn start / yarn build

yarn run v1.19.1
$ PORT=8000 react-scripts start
/bin/sh: 1: react-scripts: not found
error Command failed with exit code 127.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Timestamp Component

Maybe a simple clock showing the currently reported time on the blockchain.

Shows conversion from unix timestamp to a human readable date.

Maybe compare the time to what the browser says.

"Blockchain time vs Real Time"

UI stays active when node dies

When the node to which the UI is connected dies, the UI should return to the "Connecting to the blockchain" spinner screen. Currently the UI remains active.

Improve Extrinsics component to support multiple params

Currently the UI only supports a single input argument even though the runtime modules functions may expect a variable amount of arguments

Automatically connect to the best node possible (Connection Component)

The UI should try to automatically connect to the best node possible.

In order of priority:

• Local Node (ws://127.0.0.1:9944/)
• Dev Node (wss://dev-node.substrate.dev:9944/)
• Kusama Node
• Custom Node (input field)
• Other?

There should also be a component which allow you to set the node you want to connect to

Pallet Interactor supports Vec and Option parameters

Vec - a comma-separated list
Option - empty value to be submitted

Deployed Instance is Not Functional

It appears that the deployed instance of the template is not working. I will remove it from the repo description in the meantime.

Fix issue that SubstrateContextProvider cannot be used multiple times

This issue is also triggered if there are more than one child component directly under SubstrateContextProvider.

Contracts Component

• Import ABI
• Interact with contracts
• more?

Change license to unlicense

Event Component: Warning: Encountered two children with the same key...

The transfer component (and similar ones (eg this one)) produce an error in the js console when submitting two identical extrinsics extrinsics with the same values.

Steps to reproduce

1. Clone repo, yarn, yarn start
2. Submit a transfer (eg Alice -> Bob 12345 tokens)
3. Observe the transaction completes successfully with no errors or warnings
4. Wait several blocks (this is not a nonce / Priority is too low issue)
5. Submit another transfer with the same sender, recipient, and amount
6. Observe the error in the console (but the transaction still succeeds and the tokens are transferred)

Warning: Encountered two children with the same key, `X Blocks Ago--balances:Transfer:: (phase={"ApplyExtrinsic":2})`. Keys should be unique so that components maintain their identity across updates. Non-unique keys may cause children to be duplicated and/or omitted — the behavior is unsupported and could change in a future version.
    in div (created by Feed)
    in Feed (at Events.jsx:52)
    in div (created by GridColumn)
    in GridColumn (at Events.jsx:50)
    in Events (at App.jsx:118)
    in div (created by GridRow)
    in GridRow (at App.jsx:115)
    in div (created by Grid)
    in Grid (at App.jsx:101)
    in div (created by Container)
    in Container (at App.jsx:100)
    in App (at src/index.jsx:5)

Although the text says warning, it shows in the console as an error

Frontend-template extension

This ticket is to keep track of a list of tasks on front-end template extension so that devhub tutorial/doc can refer to using this template instead of polkadot-js app when we need front-end interaction.

This is because we have less control on polkadot-js app which may break integrating with Substrate node-template once in a while. We also gain better version control on which node- & front-end template work together.

Tasks

Extrinsics, after picking on a pallet and extrinsic function call:

• detect # of params and each param type
• allow submitting options (something in signedExtra)
• allow option of sudo
• allow option of submitting with signed or unsigned

Chain State

• allow query of pallet constants also
• after choosing pallet storage, detect # of input options needed and determine each param type. Sometimes this could be 0. Now are have hard-coded to send one option out.

Open UI on a different port

I think a lot of different web app development things try to run a server on port 3000.

I think if we have a consistent, low conflict port number, it can help docs where we may link to the localhost.

I vote we use port 8000 which is what the substrate-ui project used.

Setting up circleci

@shawntabrizi

I believe I need your permission to initialize this project to use cicleCI

Extrinsics Component

We should create a component equivalent to the "Extrinsics" tab in the Polkadot JS Apps

UI should show connection errors to the user

When failing to specify correct types (and probably other things) polkadot api puts a helpful error in the console. However this never makes it to the UI.

Just how technical of messages should be passed onto the UI is open for debate, but at least the user should know that connecting has failed and they shouldn't just sit there waiting.

The Frontend doesn't work on Windows 10

Hello,

I just followed the workflow given here and here to install substrate onto my (Windows 10)-Machine.

The Node - after quite some attempts - could compile and run successfully.
So I followed the tutorial further which brought me here in order to install the substrate frontend template.

I could however not make it run, since yarn run start will fail with

yarn run start
yarn run v1.22.0
$ PORT=8000 react-scripts start
Der Befehl "PORT" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.

(complaining trying to run PORT which is not a command). After a bit googling, I found that it will basically run that line:
"start": "PORT=8000 react-scripts start" which according to the Yarn-Docs just runs the PORT command (which is not available).

So I removed that part (in the hopes its meant as some parameter and has a reasonable default value), which actually made the server start.
However, when attempting to access the web ui, it spills me an error:

Error: Child compilation failed:
  Module build failed (from ./node_modules/react-scripts/node_modules/babel-loader/lib/index.js):
  Error: [BABEL] C:\Users\xyz\dev\substrate_frontend\node_modules\webpack\buildin\global.js: Cannot find module '@ba  bel/helper-call-delegate'
  Require stack:
  - C:\Users\Richard\dev\substrate_frontend\node_modules\babel-preset-react-app\node_modules\@babel\plugin-transform-par  ameters\lib\params.js

which made me finally report here: I guess thats not suppose to happen.

Events Component

We should create an "Events" component which allows a user to see a history of events that fired on their node.

Maybe use a pop up notification, but I am more inclined to use a "feed" instead so it is easier to look back at the history.

Unified account selection component

Currently each component that allows submitting extrinsics (Transfer, Runtime Upgrade, and Extrinsics) have their own Select from your accounts field. This will be unintuitive in a dApp-specific UI.

A better design would be to have a single account selection component (maybe rendered across in a top bar?) that allows the user to choose their account once, and any extrinsics are sent from the one selected account. This is a familiar design pattern in web UIs.

For example, here in github, I choose my account once, and any actions I take come from my account.

Linting is too agressive for a template

Recently @jimmychu0807 got eslint working. This change brought several distinct advantages, but also some disadvantages.

Advantages

• When reviewing PRs, we will see only relevant logic changes, not formatting changes
• PRs will not conflict with one another because of personal stylistic preferences
• Arbitrary style choices will not be made and unmade depending who touched the code last.

Disadvantages

• New users who may not know or care about our style conventions may be told their code doesn't compile
• Working code copied from other sources may need to be adjusted according to our linting stnadards

Possible Solutions

• Reduce stylistic linting problems to warnings rather than errors
• Enforce that linting passes in CI (so we can't merge stuff that doesn't lint) but don't display linting errors on yarn start
• Remove linting entirely -- pretty extreme, but it is an option.