Developers Home»Tutorials»Build a proof of existence dApp

Build a proof of existence dApp

This tutorial illustrates how to create a custom proof-of-existence (PoE) service using the Substrate blockchain development framework and the FRAME library.

Proof of existence is an approach to validating the authenticity and ownership of a digital object by using the object information stored on the blockchain. Because the blockchain associates a timestamp and signature with the object, the blockchain record can be used to verify—to serve as proof—that a particular object existed at a specific date and time. It can also verify who the owner of a record was at that date and time.

Digital objects and hashes

Instead of individual files, the blockchain stores digital records using a cryptographic hash. The hash enables the blockchain to store files of arbitrary size efficiently by using a small and unique hash value. Because any change to a file would result in a different hash, users can prove the validity of a file by computing the hash and comparing that hash with the hash stored on chain.

File Hash

Digital objects and account signatures

Blockchains use public keys to map digital identities to accounts that have private keys. The blockchain records the account you use to store the hash for a digital object as part of the transaction. Because the account information is stored as part of the transaction, the controller of the account can later prove ownership as the person who initially uploaded the file.

Time needed to complete this tutorial

This tutorial requires compiling Rust code and takes approximately one to two hours to complete.

Before you begin

Before you begin, verify the following:

By completing this tutorial, you will accomplish the following objectives:

  • Learn the basic structure of a custom pallet.

  • See examples of how Rust macros simplify the code you need to write.

  • Start a blockchain node that contains a custom pallet.

  • Add front-end code that exposes the proof-of-existence pallet.

Design the application

The proof of existence application exposes the following callable functions:

  • create_claim() allows a user to claim the existence of a file by uploading a hash.

  • revoke_claim() allows the current owner of a claim to revoke ownership.

These functions only require you to store information about the proofs that have been claimed, and who made those claims.

Build a custom pallet

The Substrate node template has a FRAME-based runtime. FRAME is a library of code that allows you to build a Substrate runtime by composing modules called "pallets". You can think of the pallets as individual pieces of logic that define what your blockchain can do. Substrate provides you with a number of pre-built pallets for use in FRAME-based runtimes.

Runtime composition

This tutorial shows you how to create your own FRAME pallet to be included in your custom blockchain.

Set up scaffolding for your pallet

This tutorial demonstrates how to create a custom pallet from scratch. Therefore, the first step is to remove some files and content from the files in the node template directory.

  1. Open a terminal shell and navigate to the root directory for the node template.

  2. Change to the pallets/template/src directory by running the following command:

    cd pallets/template/src

  3. Remove the following files:

    benchmarking.rs
mock.rs
tests.rs

  4. Open the pallets/template/src/lib.rs file in a text editor.

    This file contains code that you can use as a template for a new pallet. You won't be using the template code in this tutorial. However, you can review the template code to see what it provides before you delete it.

  5. Replace all contents of pallets/template/src/lib.rs with the following skeleton code that includes a few minimal macros for FRAME V2:

    //! Substrate Proof-of-Existence Pallet
#![cfg_attr(not(feature = "std"), no_std)]

// Re-export pallet items so that they can be accessed from the crate namespace.
pub use pallet::*;

#[frame_support::pallet]
pub mod pallet {
    use frame_support::{pallet_prelude::*, storage::bounded_vec::BoundedVec};
    use frame_system::pallet_prelude::*;

    // Define the pallet struct placeholder, various pallet function are implemented on it.
    #[pallet::pallet]
    #[pallet::generate_store(pub(super) trait Store)]
    pub struct Pallet<T>(_);

    // TODO: Update the `Config` block below
    /// Configure the pallet by specifying the parameters and types on which it depends.
    #[pallet::config]
    pub trait Config: frame_system::Config {
        /// Because this pallet emits events, it depends on the runtime's definition of an event.
        type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
    }

    // TODO: Update the `event` block below
    #[pallet::event]
    #[pallet::generate_deposit(pub(super) fn deposit_event)]
    pub enum Event<T: Config> {
        /// Event documentation should end with an array that provides descriptive names for event
        /// parameters. [something, who]
        SomethingHappened(),
    }
    // TODO: add #[pallet::error] block

    // TODO: add #[pallet::storage] block

    // TODO: add #[pallet::call] block
}

    You now have a scaffold that includes placeholders for events, errors, storage, and callable functions. You will replace the TODO blocks step by step to build out the full PoE pallet.

  6. Save your changes.

  7. (Optionally) check that your code compiles by running the following command:

    # Quick Check the template works *only* 
cargo check -p node-template-runtime 
# --- AND/OR ---
# Full release build of the node template, inclusive of the template
cargo build -r

    This will include some warnings, but should be compilable

Configure the pallet to emit events

Every pallet has a Rust "trait" called Config. This trait is used to set the interface for the FRAME system and sets the required associated types to be concretely defined in a runtime that includes this pallet. For this tutorial, the configuration setting only enables the pallet to emit events, as almost every pallet does.

To define the Config trait for the proof-of-existence pallet, open the pallets/template/src/lib.rs file in a text editor and update the #[pallet::config] block with to match the following code block:

    /// Configure the pallet by specifying the parameters and types on which it depends.
    #[pallet::config]
    pub trait Config: frame_system::Config {
        /// Because this pallet emits events, it depends on the runtime's definition of an event.
        type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
        /// For constraining the maximum bytes of a hash used for any proof
        type MaxBytesInHash: Get<u32>;
    }

Implement pallet events

Now that you've configured the pallet to emit events, you are ready to define those events. As described in Design the application, the proof-of-existence pallet emits an event under the following conditions:

  • When a new proof is added to the blockchain.
  • When a proof is revoked.

Each event also displays an AccountId to identify who triggered the event and the proof-of-existence data (as BoundedVec<u8, T::MaxBytesInHash>) that is being stored or removed. By convention, each event includes an array with descriptive names for its parameters.

To implement the pallet events, update the #[pallet::event] block with to match the following code block:

    // Pallets use events to inform users when important changes are made.
    // Event documentation should end with an array that provides descriptive names for parameters.
    // https://docs.substrate.io/v3/runtime/events-and-errors
    #[pallet::event]
    #[pallet::generate_deposit(pub(super) fn deposit_event)]
    pub enum Event<T: Config> {
        /// Event emitted when a proof has been claimed. [who, claim]
        ClaimCreated(T::AccountId, BoundedVec<u8, T::MaxBytesInHash>),
        /// Event emitted when a claim is revoked by the owner. [who, claim]
        ClaimRevoked(T::AccountId, BoundedVec<u8, T::MaxBytesInHash>),
    }

Include pallet errors

The events you defined indicate when calls to the pallet have completed successfully. Errors indicate when a call has failed, and why it has failed. For this tutorial, you define the following error conditions:

  • An attempt to claim a proof that has already been claimed.

  • An attempt to revoke a proof that does not exist.

  • An attempt to revoke a proof that has been claimed by another account.

To implement the errors for the proof-of-existence pallet, replace the // TODO: add #[pallet::error] block line with the following code block:

    #[pallet::error]
    pub enum Error<T> {
        /// The proof has already been claimed.
        ProofAlreadyClaimed,
        /// The proof does not exist, so it cannot be revoked.
        NoSuchProof,
        /// The proof is claimed by another account, so caller can't revoke it.
        NotProofOwner,
    }

Implement a storage map for stored items

To add a new proof to the blockchain, the proof-of-existence pallet requires a storage mechanism. To address this requirement, you can create a hash map that maps each proof to its owner and records the block number when the proof was made. To create this hash map, you can use the FRAME StorageMap trait.

To implement storage for the proof-of-existence pallet, replace the // TODO: add #[pallet::storage] block line with the following code block:

    #[pallet::storage]
    /// Maps each proof to its owner and block number when the proof was made
    pub(super) type Proofs<T: Config> = StorageMap<
        _,
        Blake2_128Concat,
        BoundedVec<u8, T::MaxBytesInHash>,
        (T::AccountId, T::BlockNumber),
        OptionQuery,
    >;

Implement callable functions

The proof-of-existence pallet exposes two callable functions to users:

  • create_claim() allows a user to claim the existence of a file with a proof.

  • revoke_claim() allows the owner of a claim to revoke the claim.

These functions use the StorageMap to implement the following logic:

  • If a proof has an owner and a block number, then it has been claimed.
  • If a proof does not have an owner and a block number, then it is available to be claimed and written to storage.

To implement this logic in the proof-of-existence pallet, replace the // TODO: add #[pallet::call] block line with the following code block:

    // Dispatchable functions allow users to interact with the pallet and invoke state changes.
    // These functions materialize as "extrinsics", which are often compared to transactions.
    // Dispatchable functions must be annotated with a weight and must return a DispatchResult.
    #[pallet::call]
    impl<T: Config> Pallet<T> {
        #[pallet::weight(1_000)]
        pub fn create_claim(
            origin: OriginFor<T>,
            proof: BoundedVec<u8, T::MaxBytesInHash>,
        ) -> DispatchResult {
            // Check that the extrinsic was signed and get the signer.
            // This function will return an error if the extrinsic is not signed.
            // https://docs.substrate.io/v3/runtime/origins
            let sender = ensure_signed(origin)?;

            // Verify that the specified proof has not already been claimed.
            ensure!(!Proofs::<T>::contains_key(&proof), Error::<T>::ProofAlreadyClaimed);

            // Get the block number from the FRAME System pallet.
            let current_block = <frame_system::Pallet<T>>::block_number();

            // Store the proof with the sender and block number.
            Proofs::<T>::insert(&proof, (&sender, current_block));

            // Emit an event that the claim was created.
            Self::deposit_event(Event::ClaimCreated(sender, proof));

            Ok(())
        }

        #[pallet::weight(10_000)]
        pub fn revoke_claim(
            origin: OriginFor<T>,
            proof: BoundedVec<u8, T::MaxBytesInHash>,
        ) -> DispatchResult {
            // Check that the extrinsic was signed and get the signer.
            // This function will return an error if the extrinsic is not signed.
            // https://docs.substrate.io/v3/runtime/origins
            let sender = ensure_signed(origin)?;

            // Verify that the specified proof has been claimed.
            ensure!(Proofs::<T>::contains_key(&proof), Error::<T>::NoSuchProof);

            // Get owner of the claim.
            // Panic condition: there is no way to set a `None` owner, so this must always unwrap.
            let (owner, _) = Proofs::<T>::get(&proof).expect("All proofs must have an owner!");

            // Verify that sender of the current call is the claim owner.
            ensure!(sender == owner, Error::<T>::NotProofOwner);

            // Remove claim from storage.
            Proofs::<T>::remove(&proof);

            // Emit an event that the claim was erased.
            Self::deposit_event(Event::ClaimRevoked(sender, proof));
            Ok(())
        }
    }

At this point you have a completed pallet! Now to use the pallet, we must correctly configure it in your runtime.

Include MaxBytesInHash runtime configuration

You should be curious that the proof-of-existence pallet uses the BoundedVec<u8, T::MaxBytesInHash> type for proofs, but thus far we have no concrete notion of what MaxBytesInHash is. This constant should be set in the runtime to something reasonable for use in your blockchain. One very typical hash type used in many web3 applications is a CID, and the V1 instance of these is typically less than 64 bytes in length. So here we specify MaxBytesInHash to be this length (or less) in the runtime:

  1. Open the runtime/src/lib.rs file in a text editor.

  2. Update the pallet_template::Config block to include:

    /// Configure the pallet-template in pallets/template.
impl pallet_template::Config for Runtime {
    type Event = Event;
    type MaxBytesInHash = frame_support::traits::ConstU32<64>;
}

  3. Save your changes and close the file.

  4. (Optionally) check that your code compiles by running the following command:

    cargo check -p node-template-runtime

Something not working? There is a full Node Template solution here to use as a reference if you're stuck. Check the commit diff from the base template for the exact changes built on the polkadot-v0.9.17 release of the templates.

Build the runtime with your new pallet

After you've copied all of the parts of the proof-of-existence pallet into the pallets/template/lib.rsfile, you are ready to compile and start the node.

To compile and start the updated Substrate node:

  1. Open a terminal shell.

  2. Change to the root directory for the node template.

  3. Compile the node template by running the following command:

    cargo build --release

  4. Start the node in development mode by running the following command:

    ./target/release/node-template --dev

    The --dev option starts the node using the predefined development chain specification. Using the --dev option ensures that you have a clean working state any time you stop and restart the node.

  5. Verify the node produces blocks.

Build a custom front-end component

Now that you have a new blockchain running with the custom proof-of-existence pallet, let's add a custom React component to the front-end template. This React component enables you to expose the proof-of-existence capabilities and interact with the new pallet you created.

Add your custom react component

  1. Open a new terminal shell on your computer, then change to the root directory where you installed the front-end template.

  2. Open the src/TemplateModule.js file in a text editor.

  3. Delete the entire contents of that file.

  4. Copy and paste the following code into thesrc/TemplateModule.js file:

    import React, { useEffect, useState } from 'react'
import { Form, Input, Grid, Message } from 'semantic-ui-react'

// Pre-built Substrate front-end utilities for connecting to a node
// and making a transaction.
import { useSubstrateState } from './substrate-lib'
import { TxButton } from './substrate-lib/components'

// Polkadot-JS utilities for hashing data.
import { blake2AsHex } from '@polkadot/util-crypto'

// Main Proof Of Existence component
function Main(props) {
  // Establish an API to talk to the Substrate node.
  const { api, currentAccount } = useSubstrateState()
  // React hooks for all the state variables we track.
  // Learn more at: https://reactjs.org/docs/hooks-intro.html
  const [status, setStatus] = useState('')
  const [digest, setDigest] = useState('')
  const [owner, setOwner] = useState('')
  const [block, setBlock] = useState(0)

  // Our `FileReader()` which is accessible from our functions below.
  let fileReader
  // Takes our file, and creates a digest using the Blake2 256 hash function
  const bufferToDigest = () => {
    // Turns the file content to a hexadecimal representation.
    const content = Array.from(new Uint8Array(fileReader.result))
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    const hash = blake2AsHex(content, 256)
    setDigest(hash)
  }

  // Callback function for when a new file is selected.
  const handleFileChosen = file => {
    fileReader = new FileReader()
    fileReader.onloadend = bufferToDigest
    fileReader.readAsArrayBuffer(file)
  }

  // React hook to update the owner and block number information for a file
  useEffect(() => {
    let unsubscribe
    // Polkadot-JS API query to the `proofs` storage item in our pallet.
    // This is a subscription, so it will always get the latest value,
    // even if it changes.
    api.query.templateModule
      .proofs(digest, result => {
        // Our storage item returns a tuple, which is represented as an array.
        if (result.inspect().inner) {
          let [tmpAddress, tmpBlock] = result.toHuman()
          setOwner(tmpAddress)
          setBlock(tmpBlock)
        } else {
          setOwner('')
          setBlock(0)
        }
      })
      .then(unsub => {
        unsubscribe = unsub
      })
    return () => unsubscribe && unsubscribe()
    // This tells the React hook to update whenever the file digest changes
    // (when a new file is chosen), or when the storage subscription says the
    // value of the storage item has updated.
  }, [digest, api.query.templateModule])

  // We *assume* a file digest is claimed if the stored block number is not 0
  function isClaimed() {
    return block !== 0
  }

  // The actual UI elements which are returned from our component.
  return (
    <Grid.Column>
      <h1>Proof of Existence</h1>
      {/* Show warning or success message if the file is or is not claimed. */}
      <Form success={!!digest && !isClaimed()} warning={isClaimed()}>
        <Form.Field>
          {/* File selector with a callback to `handleFileChosen`. */}
          <Input
            type="file"
            id="file"
            label="Your File"
            onChange={e => handleFileChosen(e.target.files[0])}
          />
          {/* Show this message if the file is available to be claimed */}
          <Message success header="File Digest Unclaimed" content={digest} />
          {/* Show this message if the file is already claimed. */}
          <Message
            warning
            header="File Digest Claimed"
            list={[digest, `Owner: ${owner}`, `Block: ${block}`]}
          />
        </Form.Field>
        {/* Buttons for interacting with the component. */}
        <Form.Field>
          {/* Button to create a claim. Only active if a file is selected, and not already claimed. Updates the `status`. */}
          <TxButton
            label="Create Claim"
            type="SIGNED-TX"
            setStatus={setStatus}
            disabled={isClaimed() || !digest}
            attrs={{
              palletRpc: 'templateModule',
              callable: 'createClaim',
              inputParams: [digest],
              paramFields: [true],
            }}
          />
          {/* Button to revoke a claim. Only active if a file is selected, and is already claimed. Updates the `status`. */}
          <TxButton
            label="Revoke Claim"
            type="SIGNED-TX"
            setStatus={setStatus}
            disabled={!isClaimed() || owner !== currentAccount.address}
            attrs={{
              palletRpc: 'templateModule',
              callable: 'revokeClaim',
              inputParams: [digest],
              paramFields: [true],
            }}
          />
        </Form.Field>
        {/* Status message about the transaction. */}
        <div style={{ overflowWrap: 'break-word' }}>{status}</div>
      </Form>
    </Grid.Column>
  )
}

export default function TemplateModule(props) {
  const { api } = useSubstrateState()
  return api.query.templateModule ? <Main {...props} /> : null
}

  5. Save your changes and close the file.

  6. Start the front-end template by running the following commands:

    nvm install # use the correct node version
yarn        # instal deps
yarn start  # start a dev server

This will open up a new tab with the front-end serving at http://localhost:8000.

Something not working? There is a full Front End Template solution here to use as a reference if you're stuck. Check the commit diff from the base template for the exact changes built on the polkadot-v0.9.17 release of the templates.

Submit a proof

To test the proof-of-existence pallet using the new front-end component:

  1. Find the component at the bottom of the page.

  2. Click Choose file and select any file on your computer.

    The proof-of-existence pallet generates the hash for the selected file and displays it in the File Digest field.

    Because the file does not have an owner or block number, it is available to claim.

  3. Click Create Claim to take ownership of the file.

    Proof Of Existence Component

    Clicking Create Claim calls the create_claim function in the custom proof-of-existence pallet. The front-end component displays the file digest, account identifier, and block number for the completed transaction.

  4. Verify the claim is successful and a new claimCreated event appears in the Events component.

    Claimed File

    The front-end component recognizes that the file is now claimed, and gives you the option to revoke the claim.

    Remember, only the owner can revoke the claim. If you select another user account, the revoke option is disabled.

Next steps

🎉Congratulations!🎉

In this tutorial, you learned the basics of how to create a new custom pallet, including:

  • How to add events, errors, storage, and callable functions to a custom pallet.

  • How to integrate the custom pallet into the runtime.

  • How to compile and start a node that includes your custom pallet.

  • How you can add a React front-end component to expose the custom pallet to users.

This tutorial covered the basics without diving too deeply into the code. However, there's much more you can do as you work toward building your own fully-customized blockchain. Custom pallets enable you to expose the features you want your blockchain to support.

To learn more about what's possible by creating custom pallets, explore the FRAME documentation and the how-to guides. For a more challenging version of this tutorial, move onto the Substrate Kitties tutorial.

Last edit: on
Run into problems?
Let us Know