Skip to main content

Building a Stateless VIDA

Stateless VIDAs are lightweight, fast, and simple applications that do not require validating or maintaining historical data or consistent state across its execution instances. They are ideal for non-critical use cases such as chat rooms, simple games, or other applications where speed and ease of development are prioritized over strict consistency.

Steps to Build a Stateless VIDA​

1. Select an ID for Your VIDA​

Every VIDA requires a unique identifier, which is an 8-byte variable. This ID ensures the PWR Chain knows which transactions belong to your application.

Why 8 bytes? It minimizes storage requirements while allowing for 18 quintillion unique IDs.

const crypto = require('crypto');

// Generate a random 64-bit integer
const vidaId = BigInt('0x' + crypto.randomBytes(8).toString('hex'));

console.log(vidaId.toString());

2. Import the PWR SDK​

The PWR SDK is your toolkit for interacting with the PWR Chain. It allows you to create wallets, send transactions, and read data from the blockchain.

import PWRJS from '@pwrjs/core';
import Wallet from '@pwrjs/core/wallet';
// or
const PWRJS = require('@pwrjs/core');
const Wallet = require('@pwrjs/core/wallet');

3. Initializing PWR with an RPC Endpoint​

To interact with the PWR Chain, initialize a PWR object (e.g., PWRJ for Java, PWRPY for Python). This object serves as your gateway to the blockchain.

What is an RPC Node?

An RPC (Remote Procedure Call) node processes blockchain requests, such as transactions and data queries. You can use a public node (e.g., https://pwrrpc.pwrlabs.io) or run your own for better control and security.

const pwrjs = new PWRJS("https://pwrrpc.pwrlabs.io/");

This setup enables seamless interaction with the PWR Chain for your VIDA.

4. Create and Fund a Wallet​

A wallet is essential for signing transactions and paying minimal fees on the PWR Chain.

  1. Create a new wallet or load an existing one.
  2. Save the wallet securely in an encrypted file.
  3. Fund it using the PWR Chain faucet (for test coins). You can check your PWR coins balance on the PWR Chain Explorer by putting your address in the search bar.
import PWRJS from '@pwrjs/core';
import Wallet from '@pwrjs/core/wallet';

const pwrjs = new PWRJS("https://pwrrpc.pwrlabs.io/");

// generate and save a new wallet
const newWallet = Wallet.newRandom(12);
console.log("Address: " + newWallet.getAddress());
newWallet.storeWallet("my_wallet.dat", "password");

//load wallet
const wallet = await Wallet.loadWallet("my_wallet.dat", "password", pwrjs);
console.log("Address: " + wallet.getAddress());

5. Define Transaction Data Structure​

While PWR Chain stores all transaction data as raw byte arrays, VIDAs can encode this data into structured formats like JSON. Defining a schema for your transactions ensures consistency, simplifies development, and enables collaboration across teams.

Why Define a Schema?

  • Consistency: Ensures all transactions follow a predictable format.
  • Documentation: Serves as a reference for developers interacting with your VIDA.
  • Validation: Helps catch malformed data early.

Example:

[
    {
        "action": "send-message-v1",
        "message": "Hello World!"
    },
    
    {
        "action": "add-reaction-v1",
        "message-hash": "0x54ef...",
        "reaction": "thumbs-up"
    }
]

6. Send Data to PWR Chain​

After defining your transaction's data structure, you can start sending transactions to PWR Chain. Submit transactions to the PWR Chain to record user actions or data.

// Write transaction data
const obj = {
    action: 'send-message-v1',
    message: 'Hello World!',
};
const data = new TextEncoder().encode(obj);

// Send transaction
const response = await wallet.sendVidaData(vidaId, data);

if(response.success) {
    console.log("Transaction sent successfully!");
    console.log("Transaction hash: " + response.hash);
}
else console.log("Transaction failed: " + response.message);

7. Read Data from PWR Chain & Handle it​

The PWR SDK provides functions to easily read and handle data from PWR Chain.

import PWRJS from "@pwrjs/core";
import { hexToBytes } from '@noble/hashes/utils';

function handler(transaction) {
    // Get the address of the transaction sender
    const sender = transaction.sender;
    // Get the data sent in the transaction (In Hex Format)
    let data = transaction.data;
    
    try {
        // Convert data string to bytes
        const bytes = hexToBytes(data);
        // Decode bytes to string and parse JSON
        const obj = JSON.parse(new TextDecoder().decode(bytes));

        // Check the action and execute the necessary code
        if (obj.action === "send-message-v1") {
            console.log(`Message from ${sender}: ${obj.message}`);
        }
    } catch (e) {
        console.error(e)
    }
}

async function main() {
    const pwrjs = new PWRJS("https://pwrrpc.pwrlabs.io/");
    const vidaId = 1n; // Replace with your VIDA's ID

    // Since our VIDA is global chat room and we don't care about historical messages,
    // we will start reading transactions startng from the latest PWR Chain block
    const startingBlock = await pwrjs.getLatestBlockNumber();
    
    const subscription = pwrjs.subscribeToVidaTransactions(
        BigInt(vidaId),
        BigInt(startingBlock),
        handler
    );

    // To pause, resume, and stop the subscription
    subscription.pause();
    subscription.resume();
    // subscription.stop();

    // To get the latest checked block
    console.log(subscription.getLatestCheckedBlock());
}
main();
  1. Make Your App Public

Once your VIDA is ready, share it with others by publishing it:

  • Option 1: Open-source your code on GitHub with clear instructions.
  • Option 2: Publish it on the PWR Chain registry for decentralized discovery. (Coming Soon)

Key Considerations for Stateless VIDAs​

  • No State Management: Stateless VIDAs do not track or validate past transactions, making them fast but unsuitable for critical use cases.
  • Ideal Use Cases: Applications prioritizing speed and simplicity over consistency (e.g., chat apps, simple games).

By following these steps, you can build a lightweight and efficient Stateless VIDA that leverages the power of PWR Chain while keeping development simple!