Welcome to the Beginners Guide to Polkadot API series! This particular tutorial will focus on learning how to build and compose decentralized applications (dApps) on the Polkadot network. We will also define what that means exactly, and how to get started with creating your first light client-powered dapp on Polkadot. In this tutorial, we will build a dead simple “You’ve Got Mail“ CLI app using the Polkadot API. build compose If you're new to Polkadot (and blockchain development) in general then keep on reading, otherwise, you can skip to the tutorial. Quick Introduction: What is Polkadot? Polkadot's is a protocol that coordinates and secures different rollups (often called parachains) allowing for a horizontally scaling, heterogeneously sharded, multi-chain approach to Web3. One of the keywords here is heterogeneously sharded, meaning that each shard, or blockchain (or state machine, if you want to get more technical), contains its unique domain-specific logic. Using the Polkadot SDK, anyone can build a rollup and inherit security from the Polkadot relay chain. A rollup can be quite literally anything from a bridge to Ethereum and other protocols (Hyperbridge), a decentralized knowledge graph️ (OriginTrail), or even a cloud computing and oracle platform that is powered by old smartphones (Acurast) coordinates secures heterogeneously sharded bridge to Ethereum and other protocols (Hyperbridge) a decentralized knowledge graph️ (OriginTrail) a cloud computing and oracle platform that is powered by old smartphones (Acurast) Once deployed, rollups can use cross-consensus messaging (XCM) to communicate with one another. This is not limited to just rollups within Polkadot, but even to other protocols, such as Ethereum. XCM Composing Applications Using the Polkadot Stack As Polkadot has a wide range of different application-specific rollups at our creative disposal, the concept of composing apps should not be a foreign one. Similar to how a traditional, web2 application may use different services, APIs, and technologies to build a fullstack application, we can utilize the different parts of the Polkadot stack to build a web3 native application. You even go as far as to host your application on a web3 service to completely bypass the conventional means of deployment. composing The Composer - The Polkadot API (PAPI) Although you can use a number of languages to build apps on Polkadot, such as Rust, Python, or Typescript/Javascript, we'll be using Polkadot API, or PAPI, which is a Typescript library for interacting with Polkadot (and its rollups). The main differentiator with PAPI is its light-client-first approach, in which it has native support for communicating to Polkadot via a light client. Polkadot API Polkadot API PAPI The light client implementation, called smoldot, runs in the background and ensures that we have the latest, verified chain state. Using PAPI, you can even interact with multiple rollups on Polkadot at once. smoldot Why Are Light Clients Important? Light clients are one of the two options for connecting to a blockchain, with the other usually depending on a single RPC provider (which often runs on a centralized server). They are typically a more secure, trust-minimized, efficient way of communicating to a blockchain. Light clients verify the state of the blockchain using Merkle proofs, ensuring it has not only the latest but correct state. As it just verifies the headers of the blocks, it has no need to download the whole state, making it ideal for resource-constrained environments. correct Unlike RPC connections, they do not depend on a single RPC provider and can be embedded in both the browser and natively. "You've Got Mail!" - Polkadot API Example With the explanation out of the way, let's get our hands dirty with some code. Project Introduction Our project will be quite simple - it will be a CLI application that runs in the terminal, which watches the relay chain for a certain extrinsic (a transaction). This extrinsic will be the system.remarkWithEvent extrinsic, meaning it is coming from the system pallet (module) on the Westend test network. extrinsic system.remarkWithEvent system The system.remarkWithEvent extrinsic allows us to send any arbitrary data on-chain, with the end result being a hash that is the address and the word "email" combined (address+email). We'll hash this combination and watch for remarks on a chain that are addressed to us. The system.remarkWithEvent extrinsic emits an event that we can use PAPI to watch the chain for. system.remarkWithEvent address+email system.remarkWithEvent Once we receive a remark addressed to us, we will play the infamous "You've Got Mail!" sound byte. Prerequisites You should have the following installed as a prerequisite: npm (or other package manager)
node
git
Polkadot.js Browser Extension (wallet) npm (or other package manager) npm node node git git Polkadot.js Browser Extension (wallet) Polkadot.js Browser Extension (wallet) You will also need an account with Westend tokens. Below you can find guides for both Polkadot.js and the faucet: Creating Accounts on Polkadot.js
Westend Faucet Creating Accounts on Polkadot.js Creating Accounts on Polkadot.js Westend Faucet Westend Faucet Cloning the repository For this tutorial, you can choose to run the example directly by cloning the main branch of the repository, or to use a boilerplate/template and follow the tutorial. main branch of the repository We need to clone the template, which has everything we need to get started with the Polkadot API and Typescript. Be sure you clone the correct branch (empty-cli) which already provides all dependencies: empty-cli git clone https://github.com/CrackTheCode016/polkadot-api-example-cli --branch empty-cli git clone https://github.com/CrackTheCode016/polkadot-api-example-cli --branch empty-cli Once cloned, run the following to ensure npm dependencies are installed: npm cd polkadot-api-example-cli
npm install cd polkadot-api-example-cli
npm install Exploring the Template (Light Clients!) When we open the repository, we should see the following code (excluding imports): async function withLightClient(): Promise<PolkadotClient> {
    // Start the light client
    const smoldot = start();
    // The Westend Relay Chain
    const relayChain = await smoldot.addChain({ chainSpec: westEndChainSpec })
    return createClient(
        getSmProvider(relayChain)
    );
}

async function main() {
    // CLI Code goes here...
}

main() async function withLightClient(): Promise<PolkadotClient> {
    // Start the light client
    const smoldot = start();
    // The Westend Relay Chain
    const relayChain = await smoldot.addChain({ chainSpec: westEndChainSpec })
    return createClient(
        getSmProvider(relayChain)
    );
}

async function main() {
    // CLI Code goes here...
}

main() The notable function to pay attention to is the withLightClient function. This function uses the built in light client functionality (powered by smoldot) to actually create a light client that syncs and interacts with Polkadot right there in our application. withLightClient smoldot Creating the CLI Next, let's create our CLI, which is to be done within the confines of the main function. We will include an option (-a / --account), which will be the account we will watch for our "mail": main -a --account const program = new Command();
console.log(chalk.white.dim(figlet.textSync("Web3 Mail Watcher")));
program.version('0.0.1').description('Web3 Mail Watcher - A simple CLI tool to watch for remarks on Polkadot network');
    .option('-a, --account <account>', 'Account to watch')
    .parse(process.argv);

// CLI Arguments from commander
const options = program.opts(); const program = new Command();
console.log(chalk.white.dim(figlet.textSync("Web3 Mail Watcher")));
program.version('0.0.1').description('Web3 Mail Watcher - A simple CLI tool to watch for remarks on Polkadot network');
    .option('-a, --account <account>', 'Account to watch')
    .parse(process.argv);

// CLI Arguments from commander
const options = program.opts(); Watching for Remarks Next, we need to start watching the Westend network for remarks sent to our account. As was done before, all code should be within the main function: main // We check for the --account flag, if its not provided we exit
    if (options.account) {
        console.log(chalk.black.bgRed("Watching account:"), chalk.bold.whiteBright(options.account));
        // We create a light client to connect to the Polkadot (Westend) network
        const lightClient = await withLightClient();
        // We get the typed API to interact with the network
        const dotApi = lightClient.getTypedApi(wnd);
        // We subscribe to the System.Remarked event and watch for remarks from our account
        dotApi.event.System.Remarked.watch().subscribe((event) => {
            // We look for a specific hash, indicating that its our address + an email
            const { sender, hash } = event.payload;
            // We calculate the hash of our account + email
            const calculatedHash = bytesToHex(blake2b(`${options.account}+email`, { dkLen: 32 }));
            // If the hash matches, we play a sound and log the message - You got mail!
            if (`0x${calculatedHash}` == hash.asHex()) {
                sound.play("youve-got-mail-sound.mp3")
                console.log(chalk.black.bgRed(`You got mail!`));
                console.log(chalk.black.bgCyan("From:"), chalk.bold.whiteBright(sender.toString()));
                console.log(chalk.black.bgBlue("Hash:"), chalk.bold.whiteBright(hash.asHex()));
            }
        });
    } else {
        // If the account is not provided, we exit
        console.error('Account is required');
        return;
    } // We check for the --account flag, if its not provided we exit
    if (options.account) {
        console.log(chalk.black.bgRed("Watching account:"), chalk.bold.whiteBright(options.account));
        // We create a light client to connect to the Polkadot (Westend) network
        const lightClient = await withLightClient();
        // We get the typed API to interact with the network
        const dotApi = lightClient.getTypedApi(wnd);
        // We subscribe to the System.Remarked event and watch for remarks from our account
        dotApi.event.System.Remarked.watch().subscribe((event) => {
            // We look for a specific hash, indicating that its our address + an email
            const { sender, hash } = event.payload;
            // We calculate the hash of our account + email
            const calculatedHash = bytesToHex(blake2b(`${options.account}+email`, { dkLen: 32 }));
            // If the hash matches, we play a sound and log the message - You got mail!
            if (`0x${calculatedHash}` == hash.asHex()) {
                sound.play("youve-got-mail-sound.mp3")
                console.log(chalk.black.bgRed(`You got mail!`));
                console.log(chalk.black.bgCyan("From:"), chalk.bold.whiteBright(sender.toString()));
                console.log(chalk.black.bgBlue("Hash:"), chalk.bold.whiteBright(hash.asHex()));
            }
        });
    } else {
        // If the account is not provided, we exit
        console.error('Account is required');
        return;
    } This code is doing quite a bit, so let's break it down: First, we check for the existance of the --account argument, and log that we are watching that account, else we exit. We are using the chalk package to add color to our console.log statements.
Next, we create our light client.
We use a light client and the Westend chain specification (wnd) to access a typed API.
Once we have our API, we then begin to reactively watch the account for the event that corresponds to the remark. We analyze the payload, looking for a hash which is calculated as follows:

hash of: account_address+email


When an event containing this hash is identified, it then plays the "You've Got Mail!" soundbite. First, we check for the existance of the --account argument, and log that we are watching that account, else we exit. We are using the chalk package to add color to our console.log statements. --account chalk console.log Next, we create our light client. We use a light client and the Westend chain specification (wnd) to access a typed API. wnd Once we have our API, we then begin to reactively watch the account for the event that corresponds to the remark. We analyze the payload, looking for a hash which is calculated as follows:

hash of: account_address+email hash of: account_address+email hash of: account_address+email account_address+email When an event containing this hash is identified, it then plays the "You've Got Mail!" soundbite. Compiling and running Once we have all of our code in place, we should compile and run the repository: npm start -- --account <account-address> npm start -- --account <account-address> Upon running, we should have the following output: ❯ npm start -- --account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY

> youve-got-mail-web3@1.0.0 start
> tsc && node ./dist/index.js --account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY

 __        __   _    _____   __  __       _ _  __        __    _       _
 \ \      / /__| |__|___ /  |  \/  | __ _(_) | \ \      / /_ _| |_ ___| |__   ___ _ __
  \ \ /\ / / _ \ '_ \ |_ \  | |\/| |/ _` | | |  \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
   \ V  V /  __/ |_) |__) | | |  | | (_| | | |   \ V  V / (_| | || (__| | | |  __/ |
    \_/\_/ \___|_.__/____/  |_|  |_|\__,_|_|_|    \_/\_/ \__,_|\__\___|_| |_|\___|_|

Watching account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
[smoldot] Smoldot v2.0.34
[smoldot] Chain initialization complete for westend2. Name: "Westend". Genesis hash: 0xe143…423e. Chain specification starting at: 0x10cf…b908 (#23920337) ❯ npm start -- --account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY

> youve-got-mail-web3@1.0.0 start
> tsc && node ./dist/index.js --account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY

 __        __   _    _____   __  __       _ _  __        __    _       _
 \ \      / /__| |__|___ /  |  \/  | __ _(_) | \ \      / /_ _| |_ ___| |__   ___ _ __
  \ \ /\ / / _ \ '_ \ |_ \  | |\/| |/ _` | | |  \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
   \ V  V /  __/ |_) |__) | | |  | | (_| | | |   \ V  V / (_| | || (__| | | |  __/ |
    \_/\_/ \___|_.__/____/  |_|  |_|\__,_|_|_|    \_/\_/ \__,_|\__\___|_| |_|\___|_|

Watching account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
[smoldot] Smoldot v2.0.34
[smoldot] Chain initialization complete for westend2. Name: "Westend". Genesis hash: 0xe143…423e. Chain specification starting at: 0x10cf…b908 (#23920337) Testing the CLI Now that our application is actively watching for remark events on-chain, we can move to testing to see if it works! As mentioned previously, you will need a Westend account with some tokens to pay for fees. As mentioned previously, you will need a Westend account with some tokens to pay for fees. Navigate to the PAPI Dev Console > Extrinsics. You then want to select the System pallet, and the remark_with_event call: PAPI Dev Console > Extrinsics System remark_with_event Next, we want to be sure we get the correct input for the text field. We want to be sure we are following the convention we set forth in our application: address+email address+email address+email address+email If for example, we are watching 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY, then the field should look like the following: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY Once this input is in place, you may click the Submit extrinsic button, where you can sign using the Polkadot.js browser wallet: Submit extrinsic Heading back to our CLI, we should soon see the following, along with the fact that "YOU'VE GOT MAIL!" (as in the sound should play): __        __   _    _____   __  __       _ _  __        __    _       _
 \ \      / /__| |__|___ /  |  \/  | __ _(_) | \ \      / /_ _| |_ ___| |__   ___ _ __
  \ \ /\ / / _ \ '_ \ |_ \  | |\/| |/ _` | | |  \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
   \ V  V /  __/ |_) |__) | | |  | | (_| | | |   \ V  V / (_| | || (__| | | |  __/ |
    \_/\_/ \___|_.__/____/  |_|  |_|\__,_|_|_|    \_/\_/ \__,_|\__\___|_| |_|\___|_|

Watching account: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
You've got mail!
From: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
Hash: 0xb6999c9082f5b1dede08b387404c9eb4eb2deee4781415dfa7edf08b87472050 __        __   _    _____   __  __       _ _  __        __    _       _
 \ \      / /__| |__|___ /  |  \/  | __ _(_) | \ \      / /_ _| |_ ___| |__   ___ _ __
  \ \ /\ / / _ \ '_ \ |_ \  | |\/| |/ _` | | |  \ \ /\ / / _` | __/ __| '_ \ / _ \ '__|
   \ V  V /  __/ |_) |__) | | |  | | (_| | | |   \ V  V / (_| | || (__| | | |  __/ |
    \_/\_/ \___|_.__/____/  |_|  |_|\__,_|_|_|    \_/\_/ \__,_|\__\___|_| |_|\___|_|

Watching account: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
You've got mail!
From: 5Cm8yiG45rqrpyV2zPLrbtr8efksrRuCXcqcB4xj8AejfcTB
Hash: 0xb6999c9082f5b1dede08b387404c9eb4eb2deee4781415dfa7edf08b87472050 Conclusion This application can be expanded in a number of ways, whether that is by adding a chatroom through remarks, or by using some of the rollups on Polkadot to expand the functionality. If you have any ideas, questions, comments, or concerns, feel free to shoot me a message here on X! X

This story contains new, firsthand information uncovered by the writer.

The code in this story is for educational purposes. The readers are solely responsible for whatever they build with it.

Everything You Need to Know About The Polkadot API (PAPI)

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

A Normie Intro to Web3 in 2023 (And How it Differs from Web2)

The Noonification: How to Implement a Merkle Tree in Solidity (11/12/2023)

30% of Newly Minted NCT is Owned by Addresses that Don't Own a Hashmask

7 Dapp Platforms to Follow in 2021

DApps 101: Decoding Legality, Privacy, and Token Security

A Normie Intro to Web3 in 2023 (And How it Differs from Web2)

The Noonification: How to Implement a Merkle Tree in Solidity (11/12/2023)

30% of Newly Minted NCT is Owned by Addresses that Don't Own a Hashmask

7 Dapp Platforms to Follow in 2021

DApps 101: Decoding Legality, Privacy, and Token Security

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps