Polkadot.js integration for Blackprint

This module gives you an ability to use Polkadot.js's APIs with Blackprint.

Quick walkthrough on how to load module and open some example

If the video looks blurry, please play it in fullscreen

walkthrough.mp4

Below is the summary and some information of the video:

1. Open Blackprint editor's sketch page
2. Creating notes node (this module get loaded when you choose the example)
3. Load nodes-polkadot.js module from NPM repository
   • You may see a loading progress on your first try
4. Creating new nodes from nodes-polkadot.js module
5. Opening example that get loaded to our editor when we choose the module
   • The example is loaded from the published release on NPM registry
   • But you can also manually copy paste the JSON content from the /example directory to load it on the editor
6. Open encrypt/decrypt example
   • If the published example for encrypt/decrypt was looks compact and complicated, please import from the updated /example instead
   • On this example there are 2 keypair that is randomly generated, the address may different and causes the Decrypt Data node can't decrypted the data from Encrypt Data node because the author address was different
   • You will need to copy Alice's wallet address from Log node to Input node that connected to Encrypt Data, the node then will encrypt the data with Alice's public key/wallet address
   • The testing message will now get encrypted for Alice's wallet from Bob's wallet and can be decrypted by Alice's wallet where the author is Bob's wallet
7. Open sign verify: extension example
   • On your first try, you may need to allow Blackprint on your Polkadot.js's browser extension
   • Then, please copy your wallet address for testing into the input box
   • After you connect the signer, it will ask your extension to sign the message: testing
   • By the way if you see an error message on my DevTools, it's because I canceled the extension to sign the message

What you can do with Blackprint?

Blackprint is designed to be flexible, it's not limited to browser only or for web development only. For an example you can also build a Telegram bot with Blackprint for sending balances between account:

If the video looks blurry, please play it in fullscreen

Polkadot-Telegram-bot.mp4

---

Examples

Click this link to open example list in Blackprint Editor.

You can also manually import a JSON for Blackprint Editor from /example directory.

This repository also have example Dockerfiles in case if you want to run the unit test, and run example project for Node.js or Deno in isolated environment.

Run in different environment

Blackprint is designed to be able to run in multiple environment, you can also easily export your schema into JSON and run it in Node.js, Deno, or browser. Below is a quick and simple tutorial that can help you getting started:

Click this to open the guide for Deno

When using Deno, it's pretty easy to start with as you can easily import module with URL natively. Let's get straight into the code, for a quick start you can copy and paste the code below:

import Blackprint from 'https://cdn.skypack.dev/@blackprint/engine';

// Only allow load module from specific domain
Blackprint.allowModuleOrigin('cdn.jsdelivr.net');

// Fix the bundled version of Polkadot.js's library for Deno
globalThis.location = { href: '' };

// Create the instance and import the JSON
let MyInstance = new Blackprint.Engine();
await MyInstance.importJSON(`{ ... }`);

// Don't forget to add an ID to your node so you can easily access it like below
let { your_node_id, other_node_id } = MyInstance.ref;

After you replaced the JSON, you can run the app with:

$ deno run --allow-net ./init.mjs

blackprint-polkadot-deno.mp4

---

Click this to open the guide for Node.js

When using Node.js you will need to install the Blackprint Engine and the modules. But you can also import the module via URL and it will be downloaded when you run your app.

$ cd /your/project/folder
$ npm init
$ pnpm i @blackprint/engine @blackprint/nodes-polkadot.js

For a quick start, you can copy and paste the code below:

import Blackprint from "@blackprint/engine";

// For this module on Node.js, you must import/install this module manually as it has dependencies
import "@blackprint/nodes-polkadot.js/dist/nodes-polkadotjs.mjs";

let json = { ... };

// Remove Polkadot module URL as it already been loaded manually
json._.moduleJS = json._.moduleJS.filter(url => !url.includes('@blackprint/nodes-polkadot.js'));

// Only allow load module from specific domain (if using URL module loader)
Blackprint.allowModuleOrigin('cdn.jsdelivr.net');

// Create the instance and import the JSON
let MyInstance = new Blackprint.Engine();
await MyInstance.importJSON(json);

// Don't forget to add an ID to your node so you can easily access it like below
let { your_node_id, other_node_id } = MyInstance.ref;

After you replaced the JSON, you can run the app with:

$ node ./init.mjs

# If you want to use HTTPS module loader you need to use this
$ node --loader ./node_modules/@blackprint/engine/es6-https-loader.mjs ./init.mjs

blackprint-polkadot-nodejs.mp4

---

Click this to open the guide for Browser

For browser, you will need to import the Blackprint Engine and the Vue framework. Below is the HTML example if you want to use CDN to load the library:

<head>
  <!-- Blackprint Engine -->
  <script src="https://cdn.jsdelivr.net/npm/@blackprint/engine"></script>
  
  <!-- Vue 3 -->
  <script src="https://unpkg.com/vue@next"></script>
</head>

If you prefer to use bundler like Webpack or Vite, you may need to install the module with a package manager first:

$ pnpm install @blackprint/engine vue@next

After that you can write your Vue template and bind the engine instance with your Vue app:

<body>
  <!-- Your Vue template -->
  <div id="v-model-basic">
    Port value: {{ your_node_id.Output.MyPort }}

    <input @input="your_node_id.Input.MyPortIn = $event.target.value">
  </div>

  <script>
    // Only allow module import from cdn.jsdelivr.net  
    Blackprint.allowModuleOrigin('cdn.jsdelivr.net');

    // Create new engine instance
    var instance = new Blackprint.Engine();

    // You can copy paste this to Blackprint Editor
    instance.importJSON(`{ ... }`).then(function(){
      // Create Vue app and bind the Blackprint port references with the app
      Vue.createApp({
        data() {
          // Obtain Interface by ID and get the port references
          let { your_node_id, other_node_id } = instance.ref;

          // Vue 3 is using Proxy for their reactivity
          // You may need to use event listener and update Vue element's value manually like:
          your_node_id.IOutput.MyPort.on('value', ({ port })=> this.myProp = port.value);

          // Put the ports reference to this component scope
          return { your_node_id, other_node_id };
        }
      }).mount('#v-model-basic');
    });
  </script>
</body>

That's it, don't forget to add an ID to your node so you can easily access it from instance.ref.

Some example:

1. Blackprint + Vue 3
2. Blackprint + React

---

Development

If you want to help contributing with this Blackprint module, you can follow instruction below. But if you just want to use this module for your project, you can open this example list on Blackprint Editor or just import the module for your app with Node.js or Deno project.

You will need to clone this repository and install the required dependencies.

# You can also use npm or yarn instead of pnpm
$ pnpm install

Watch changes and run a local module server

By running local server you can ask Blackprint Editor to connect into it to enjoy hot reload.
If you only want to do a testing, please skip this step.

$ npm start
 >> [Browsersync] Access URLs:
 >> -----------------------------------
 >> Local: http://localhost:6789
 >> ---------------

Click here to see more detail

After running the module server, you can go to https://blackprint.github.io/dev.html and open a new sketch. Click the main menu on the top left and click Remote -> Module, then paste your module server's URL the click Connect.

Build and minify

Bundle every files and minify it into 3 distributable file.

$ npm run build-prod

Running Test

• We will use Jest to do the testing for Browser and Node.js
• Before running this test, make sure you have build this module
• Westend's testnet will be used (My mnemonic is stored on GitHub Action's secrets)
• If you're going to test from your environment, please rename .env.example to .env and edit it
• Address for ChainId: 42
  • Wallet A: 5CPKqqEXE3YHKProqt5e6o8Lw9xBSdpf5Ex44U5WjL82yKPj
  • Wallet B: 5CdiLQpHyeJJsdgP5azER3dtBmgRTNhYQhLxRdmBmRqXQRGH

$ npm test

Import this nodes from URL

If you're planning to develop your own sketch/editor for your project, there are some example on the Blackprint repository to help you get started on how to implement the sketch or use the engine with another framework.

Please specify the version to avoid breaking changes.

Blackprint.loadModuleFromURL([
  'https://cdn.jsdelivr.net/npm/@blackprint/nodes-polkadot.js@0.8.x/dist/nodes-polkadotjs.mjs'
], {
  // Turn this on if you want to load ".sf.js" and ".sf.css" for browser
  loadBrowserInterface: true // set to "false" for Node.js/Deno
});

Load unpublished module from GitHub

You can use this link to load unpublished nodes that still under development on GitHub.
https://cdn.jsdelivr.net/gh/Blackprint/nodes-polkadot.js@dist/nodes-polkadotjs.mjs

Replace dist with your latest commit hash (from dist branch) to avoid cache from CDN.

Distributable files

All files inside src folder will be bundled into 3 distributable file. Some file is optional to be loaded on the target environment.

// all .js files
- dist/nodes-polkadotjs.mjs    // For browser, Node.js, and Deno (required)

// all .sf files
- dist/nodes-polkadotjs.sf.mjs // For browser only (required)
- dist/nodes-polkadotjs.sf.css // For browser only (optional)

Directory structure

Configuration file can be changed from ./blackprint.config.js.
The src directory structure is arranged like below:

File path	Blackprint Node path
./src/Account/Transfer/Balance.js	Polkadot.js/Account/Transfer/Balance
./src/Connection/WebSocket.js	Polkadot.js/Connection/WebSocket

With the above structure, you can easily find the nodes on Blackprint Editor like below:

License

This module is released with MIT license and depends on Polkadot.js library with Apache 2.0 license.