Extend examples for ApiPromise (#261)

* examples-rpc -> examples/rpc * 01-simple-connect * 02-chain-newHead * Subscriptions only return value
2018-10-12 11:19:35 +02:00
parent d870b54d8d
commit 8fafedcf00
47 changed files with 153 additions and 45 deletions
@@ -9,11 +9,11 @@

 ## Examples

- [RPC](examples-rpc/README.md)
-  - [Simple connect](examples-rpc/01_simple_connect/README.md)
-  - [Listen to blocks](examples-rpc/02_listen_to_blocks/README.md)
-  - [Listen to balance change](examples-rpc/03_listen_to_balance_change/README.md)
-  - [Generate Accounts](examples-rpc/04_generate_account/README.md)
-  - [Read Storage](examples-rpc/05_read_storage/README.md)
-  - [Craft Extrinsic](examples-rpc/06_craft_extrinsic/README.md)
-  - [Transfer DOTs](examples-rpc/07_transfer_dots/README.md)
+- [ApiPromise](examples/promise/README.md)
+  - [Simple connect](examples/promise/01_simple_connect/README.md)
+  - [Listen to blocks](examples/promise/02_listen_to_blocks/README.md)
+  - [Listen to balance change](examples/deprecated-rpc/03_listen_to_balance_change/README.md)
+  - [Generate Accounts](examples/deprecated-rpc/04_generate_account/README.md)
+  - [Read Storage](examples/deprecated-rpc/05_read_storage/README.md)
+  - [Craft Extrinsic](examples/deprecated-rpc/06_craft_extrinsic/README.md)
+  - [Transfer DOTs](examples/deprecated-rpc/07_transfer_dots/README.md)
@@ -426,7 +426,7 @@
    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"Simple connect","level":"2.1.1","depth":2,"next":{"title":"Listen to blocks","level":"2.1.2","depth":2,"path":"examples-rpc/02_listen_to_blocks/README.md","ref":"examples-rpc/02_listen_to_blocks/README.md","articles":[]},"previous":{"title":"RPC","level":"2.1","depth":1,"path":"examples-rpc/README.md","ref":"examples-rpc/README.md","articles":[{"title":"Simple connect","level":"2.1.1","depth":2,"path":"examples-rpc/01_simple_connect/README.md","ref":"examples-rpc/01_simple_connect/README.md","articles":[]},{"title":"Listen to blocks","level":"2.1.2","depth":2,"path":"examples-rpc/02_listen_to_blocks/README.md","ref":"examples-rpc/02_listen_to_blocks/README.md","articles":[]},{"title":"Listen to balance change","level":"2.1.3","depth":2,"path":"examples-rpc/03_listen_to_balance_change/README.md","ref":"examples-rpc/03_listen_to_balance_change/README.md","articles":[]},{"title":"Generate Accounts","level":"2.1.4","depth":2,"path":"examples-rpc/04_generate_account/README.md","ref":"examples-rpc/04_generate_account/README.md","articles":[]},{"title":"Read Storage","level":"2.1.5","depth":2,"path":"examples-rpc/05_read_storage/README.md","ref":"examples-rpc/05_read_storage/README.md","articles":[]},{"title":"Craft Extrinsic","level":"2.1.6","depth":2,"path":"examples-rpc/06_craft_extrinsic/README.md","ref":"examples-rpc/06_craft_extrinsic/README.md","articles":[]},{"title":"Transfer DOTs","level":"2.1.7","depth":2,"path":"examples-rpc/07_transfer_dots/README.md","ref":"examples-rpc/07_transfer_dots/README.md","articles":[]}]},"dir":"ltr"},"config":{"plugins":["include-codeblock","mermaid-gb3","-highlight","sunlight-highlighter"],"root":"docs","styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"sunlight-highlighter":{"theme":"gitbook","lineNumbers":false},"include-codeblock":{"check":false,"edit":false,"lang":"","fixlang":false,"template":"default","theme":"chrome","unindent":false},"mermaid-gb3":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Polkadot API Book","gitbook":">=2.4.0"},"file":{"path":"examples-rpc/01_simple_connect/README.md","mtime":"2018-10-12T07:36:16.547Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-12T07:40:02.850Z"},"basePath":"../..","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"Simple connect","level":"2.1.1","depth":2,"next":{"title":"Listen to blocks","level":"2.1.2","depth":2,"path":"examples-rpc/02_listen_to_blocks/README.md","ref":"examples-rpc/02_listen_to_blocks/README.md","articles":[]},"previous":{"title":"RPC","level":"2.1","depth":1,"path":"examples-rpc/README.md","ref":"examples-rpc/README.md","articles":[{"title":"Simple connect","level":"2.1.1","depth":2,"path":"examples-rpc/01_simple_connect/README.md","ref":"examples-rpc/01_simple_connect/README.md","articles":[]},{"title":"Listen to blocks","level":"2.1.2","depth":2,"path":"examples-rpc/02_listen_to_blocks/README.md","ref":"examples-rpc/02_listen_to_blocks/README.md","articles":[]},{"title":"Listen to balance change","level":"2.1.3","depth":2,"path":"examples-rpc/03_listen_to_balance_change/README.md","ref":"examples-rpc/03_listen_to_balance_change/README.md","articles":[]},{"title":"Generate Accounts","level":"2.1.4","depth":2,"path":"examples-rpc/04_generate_account/README.md","ref":"examples-rpc/04_generate_account/README.md","articles":[]},{"title":"Read Storage","level":"2.1.5","depth":2,"path":"examples-rpc/05_read_storage/README.md","ref":"examples-rpc/05_read_storage/README.md","articles":[]},{"title":"Craft Extrinsic","level":"2.1.6","depth":2,"path":"examples-rpc/06_craft_extrinsic/README.md","ref":"examples-rpc/06_craft_extrinsic/README.md","articles":[]},{"title":"Transfer DOTs","level":"2.1.7","depth":2,"path":"examples-rpc/07_transfer_dots/README.md","ref":"examples-rpc/07_transfer_dots/README.md","articles":[]}]},"dir":"ltr"},"config":{"plugins":["include-codeblock","mermaid-gb3","-highlight","sunlight-highlighter"],"root":"docs","styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"sunlight-highlighter":{"theme":"gitbook","lineNumbers":false},"include-codeblock":{"check":false,"edit":false,"lang":"","fixlang":false,"template":"default","theme":"chrome","unindent":false},"mermaid-gb3":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Polkadot API Book","gitbook":">=2.4.0"},"file":{"path":"examples-rpc/01_simple_connect/README.md","mtime":"2018-10-11T19:36:42.041Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-11T19:40:38.728Z"},"basePath":"../..","book":{"language":""}});
        });
    </script>
 </div>
@@ -0,0 +1,5 @@
+# Simple Connect
+
+The following example shows how to instantiate a Polkadot API object and use it to connect to a node.
+
+[include](index.js)
@@ -0,0 +1,18 @@
+// required imports
+const { ApiPromise } = require('@polkadot/api');
+const { WsProvider } = require('@polkadot/rpc-provider');
+
+async function main () {
+  // initialise the provider to connect to the local node
+  const provider = new WsProvider('ws://127.0.0.1:9944');
+
+  // create the API and wait until ready
+  const api = await ApiPromise.create(provider);
+
+  // retrieve the chain information (rpc call)
+  const chain = await api.rpc.system.chain();
+
+  console.log(`You are connected to chain: ${chain}`);
+}
+
+main().catch(console.error).finally(() => process.exit());
@@ -0,0 +1,20 @@
+{
+  "name": "01_simple_connect",
+  "version": "0.1.0",
+  "description": "Example showing how to connect using a WebSocket",
+  "main": "index.js",
+  "author": "chevdor",
+  "license": "MIT",
+  "scripts": {
+    "clean": "rimraf node_modules",
+    "start": "node index.js"
+  },
+
+  "dependencies": {
+    "@polkadot/api": "^0.31.15",
+    "@polkadot/rpc-provider": "^0.31.15"
+  },
+  "devDependencies": {
+    "rimraf": "^2.6.2"
+  }
+}
@@ -0,0 +1,9 @@
+# Listen to new blocks
+
+This example shows how to subscribe to new blocks.
+
+It displays the block number every time a new block is seen by the node you are connected to.
+
+NOTE: The example runs until you stop it with CTRL+C
+
+[include](index.js)
@@ -0,0 +1,22 @@
+// API imports
+const { ApiPromise } = require('@polkadot/api');
+
+async function main () {
+  // Here we don't pass the (optional) provider, connecting directly to the default
+  // node/port, i.e. `ws://127.0.0.1:9944`. Await for the isReady promise to ensure
+  // the API has connected to the node and completed the initialisation process
+  const api = await new ApiPromise().isReady;
+
+  // Subscribe to the new headers on-chain. The callback is fired when new headers
+  // are found, the call itself returns a promise with a subscription that can be
+  // used to unsubscribe from the newHead subscription
+  const subsciptionId = await api.rpc.chain.newHead((header) => {
+    console.log(`best #${header.blockNumber.toString()}`);
+  });
+
+  // id for the subscription, we can cleanup and unsubscribe via
+  // `api.chain.newHead.unsubscribe(subscriptionId)`
+  console.log(`subsciptionId: ${subsciptionId}`);
+}
+
+main().catch(console.error);
@@ -0,0 +1,18 @@
+{
+  "name": "02_listen_to_blocks",
+  "version": "0.1.0",
+  "description": "Example showing how to use subscriptions",
+  "main": "index.js",
+  "author": "chevdor",
+  "license": "MIT",
+  "scripts": {
+    "clean": "rimraf node_modules",
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@polkadot/api": "^0.31.15"
+  },
+  "devDependencies": {
+    "rimraf": "^2.6.2"
+  }
+}
@@ -0,0 +1,26 @@
+# ApiPromise Examples
+
+Here you will find a list of examples that takes you through the basics of connecting to a local node, retrieving data from the Node and chain and execute transactions on the chain. It uses the [[ApiPromise]] interface.
+
+## Prerequisites
+
+For the following examples, you need a local node. It is usually convenient testing with:
+
+```
+substrate --dev
+```
+
+## Running the examples
+
+From each folder, run `yarn` to install the required dependencies and then run `yarn start` to execute the example against the running node.
+
+## Development accounts
+
+Some of the examples use the following accounts:
+
+- Alice: `5GoKvZWG5ZPYL1WUovuHW3zJBWBP5eT8CbqjdRY4Q6iMaDtZ`
+- Bob: `5Gw3s7q4QLkSWwknsiPtjujPv3XM4Trxi5d4PgKMMk3gfGTE`
+
+Those accounts are easy to add if you don't have/see them. The seed of Alice's account is `Alice␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣␣` and the seed of Bob is... well you guess...
+
+NOTE: Note the spaces padding Alice's key up to 32 chars.