Skip to content

Commit e2ae5b7

Browse files
CrackTheCode016CrackTheCode016
authored
PAPI CLI Tutorial and dApp/Client Side IA (#486)
* draft tutorial and ia * draft ia and tutorial * tutorial polish * address feedback + image * more polish
1 parent b3f0cfd commit e2ae5b7

File tree

7 files changed

+191
-0
lines changed

7 files changed

+191
-0
lines changed

‎images/develop/dapps/papi/papi-console.webp‎

48.7 KB
Loading

‎tutorials/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ nav:
44
- polkadot-sdk
55
- interoperability
66
- onchain-governance
7+
- dapps

‎tutorials/dapps/.pages‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
title: dApps
2+
nav:
3+
- index.md
4+
- papi

‎tutorials/dapps/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Decentralized Application Tutorials
3+
description: Explore step-by-step tutorials for exploring the world of building decentralized applications using the toolkits that Polkadot provides.
4+
template: index-page.html
5+
---

‎tutorials/dapps/papi/.pages‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
title: Polkadot API (PAPI)
2+
nav:
3+
- index.md
4+
- remark-tutorial.md

‎tutorials/dapps/papi/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Polkadot API (PAPI) Tutorials
3+
description: Explore step-by-step tutorials for building applications using the Polkadot API.
4+
template: index-page.html
5+
---

‎tutorials/dapps/papi/remark-tutorial.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
title: Polkadot API Account Watcher Tutorial
3+
description: Learn how to build a decentralized command-line application using the Polkadot API.
4+
---
5+
6+
!!!info "This tutorial uses the Westend Test Network"
7+
Ensure you have an account with WND tokens before proceeding with this tutorial.
8+
9+
## Introduction
10+
11+
This tutorial demonstrates how to build a simple command-line interface (CLI) application that monitors a user's account on the relay chain for the `system.remarkWithEvent` extrinsic.
12+
13+
The `system.remarkWithEvent` extrinsic enables the submission of arbitrary data on-chain. In this tutorial, the data consists of a hash derived from the combination of an account address and the word "email" (`address+email`). This hash is monitored on-chain, and the application listens for remarks addressed to the specified account. The `system.remarkWithEvent` extrinsic emits an event that can be observed using the Polkadot API (PAPI).
14+
15+
When the application detects a remark addressed to the specified account, it plays the "You've Got Mail!" sound byte.
16+
17+
## Prerequisites
18+
19+
Before starting, ensure the following tools and dependencies are installed:
20+
21+
- `npm` (or an alternative package manager)
22+
- `node`
23+
- `git`
24+
- [Polkadot.js Browser Extension (wallet)](https://polkadot.js.org/extension/){target=\_blank}
25+
26+
Additionally, you need an account with Westend tokens. Refer to the following resources for assistance:
27+
28+
- [Westend Faucet](https://faucet.polkadot.io/westend){target=\_blank}
29+
30+
## Clone the Repository
31+
32+
To follow this tutorial, you can either run the example directly or use a boilerplate/template. This tutorial uses a template that includes all necessary dependencies for working with the Polkadot API and TypeScript. Clone the appropriate branch (`empty-cli`) of the repository as follows:
33+
34+
```shell
35+
git clone https://github.com/CrackTheCode016/polkadot-api-example-cli --branch empty-cli
36+
```
37+
38+
After cloning, install the required dependencies by running:
39+
40+
```shell
41+
cd polkadot-api-example-cli
42+
npm install
43+
```
44+
45+
## Explore the Template (Light Clients)
46+
47+
After opening the repository, you will find the following code (excluding imports):
48+
49+
```typescript
50+
// filepath: /path/to/repository/src/index.ts
51+
async function withLightClient(): Promise<PolkadotClient> {
52+
// Start the light client
53+
const smoldot = start();
54+
// The Westend Relay Chain
55+
const relayChain = await smoldot.addChain({ chainSpec: westEndChainSpec });
56+
return createClient(
57+
getSmProvider(relayChain)
58+
);
59+
}
60+
61+
async function main() {
62+
// CLI code goes here...
63+
}
64+
65+
main();
66+
```
67+
68+
The `withLightClient` function is particularly important. It uses the built-in light client functionality, powered by [`smoldot`](https://github.com/smol-dot/smoldot){target=\_blank}, to create a light client that synchronizes and interacts with Polkadot directly within the application.
69+
70+
## Create the CLI
71+
72+
The CLI functionality is implemented within the `main` function. The CLI includes an option (`-a` / `--account`) to specify the account to monitor for remarks:
73+
74+
```typescript
75+
// filepath: /path/to/repository/src/index.ts
76+
const program = new Command();
77+
console.log(chalk.white.dim(figlet.textSync("Web3 Mail Watcher")));
78+
program
79+
.version('0.0.1')
80+
.description('Web3 Mail Watcher - A simple CLI tool to watch for remarks on the Polkadot network')
81+
.option('-a, --account <account>', 'Account to watch')
82+
.parse(process.argv);
83+
84+
// CLI arguments from commander
85+
const options = program.opts();
86+
```
87+
88+
## Watch for Remarks
89+
90+
The application monitors the Westend network for remarks sent to the specified account. The following code, placed within the `main` function, implements this functionality:
91+
92+
```typescript
93+
// filepath: /path/to/repository/src/index.ts
94+
if (options.account) {
95+
console.log(chalk.black.bgRed("Watching account:"), chalk.bold.whiteBright(options.account));
96+
// Create a light client to connect to the Polkadot (Westend) network
97+
const lightClient = await withLightClient();
98+
// Get the typed API to interact with the network
99+
const dotApi = lightClient.getTypedApi(wnd);
100+
// Subscribe to the System.Remarked event and watch for remarks from the account
101+
dotApi.event.System.Remarked.watch().subscribe((event) => {
102+
const { sender, hash } = event.payload;
103+
const calculatedHash = bytesToHex(blake2b(`${options.account}+email`, { dkLen: 32 }));
104+
if (`0x${calculatedHash}` === hash.asHex()) {
105+
sound.play("youve-got-mail-sound.mp3");
106+
console.log(chalk.black.bgRed("You got mail!"));
107+
console.log(chalk.black.bgCyan("From:"), chalk.bold.whiteBright(sender.toString()));
108+
console.log(chalk.black.bgBlue("Hash:"), chalk.bold.whiteBright(hash.asHex()));
109+
}
110+
});
111+
} else {
112+
console.error('Account is required');
113+
return;
114+
}
115+
```
116+
117+
## Compile and Run
118+
119+
Compile and execute the application using the following command:
120+
121+
```shell
122+
npm start -- --account <account-address>
123+
```
124+
125+
For example:
126+
127+
```shell
128+
npm start -- --account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
129+
```
130+
131+
The output should look like this:
132+
133+
```
134+
__ __ _ _____ __ __ _ _ __ __ _ _
135+
\ \ / /__| |__|___ / | \/ | __ _(_) | \ \ / /_ _| |_ ___| |__ ___ _ __
136+
\ \ /\ / / _ \ '_ \ |_ \ | |\/| |/ _` | | | \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
137+
\ V V / __/ |_) |__) | | | | | (_| | | | \ V V / (_| | || (__| | | | __/ |
138+
\_/\_/ \___|_.__/____/ |_| |_|\__,_|_|_| \_/\_/ \__,_|\__\___|_| |_|\___|_|
139+
140+
Watching account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
141+
[smoldot] Smoldot v2.0.34
142+
[smoldot] Chain initialization complete for westend2. Name: "Westend". Genesis hash: 0xe143…423e. Chain specification starting at: 0x10cf…b908 (#23920337)
143+
```
144+
145+
## Test the CLI
146+
147+
To test the application, navigate to the [PAPI Dev Console > Extrinsics](https://dev.papi.how/extrinsics#networkId=westend&endpoint=light-client){target=\_blank}. Select the `System` pallet and the `remark_with_event` call.
148+
149+
Ensure the input field follows the convention `address+email`. For example, if monitoring `5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY`, the input should be:
150+
151+
![](images/develop/dapps/papi/papi-console.webp)
152+
153+
Submit the extrinsic and sign it using the Polkadot.js browser wallet. The CLI will display the following output and play the "You've Got Mail!" sound:
154+
155+
```
156+
__ __ _ _____ __ __ _ _ __ __ _ _
157+
\ \ / /__| |__|___ / | \/ | __ _(_) | \ \ / /_ _| |_ ___| |__ ___ _ __
158+
\ \ /\ / / _ \ '_ \ |_ \ | |\/| |/ _` | | | \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
159+
\ V V / __/ |_) |__) | | | | | (_| | | | \ V V / (_| | || (__| | | | __/ |
160+
\_/\_/ \___|_.__/____/ |_| |_|\__,_|_|_| \_/\_/ \__,_|\__\___|_| |_|\___|_|
161+
162+
Watching account: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
163+
You've got mail!
164+
From: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
165+
Hash: 0xb6999c9082f5b1dede08b387404c9eb4eb2deee4781415dfa7edf08b87472050
166+
```
167+
168+
## Next Steps
169+
170+
This application demonstrates how the Polkadot API can be used to build decentralized applications. While this is not a production-grade application, it introduces several key features for developing with the Polkadot API.
171+
172+
To explore more, refer to the [official PAPI documentation](https://papi.how){target=\_blank}.

0 commit comments

Comments
 (0)