DEV Community

Cover image for An Introduction To Blockchain Application Development — Part 2/2
Kristjan Kosic
Kristjan Kosic

Posted on • Originally published at blog.ark.io

An Introduction To Blockchain Application Development — Part 2/2

#blockchain #typescript #tutorial #showdev

In this post, we will take a deep-dive into developing custom transaction types with our Core GTI (Generic Transaction Interface) technology.

We will learn how to add the new business logic to a blockchain by introducing custom transaction types tailored to your application needs. You will learn how to:

  1. Implement a new transaction type structure and introduce custom fields
  2. Implement a new custom transaction builder class
  3. Implement a general transaction handler that hooks our newly created transaction type with the blockchain protocol
  4. Use existing API interfaces to interact with core blockchain and new transaction types.

Related posts:

In the previous post, Part 1 — The Introduction To Blockchain Development with ARK, we addressed the developing of distributed blockchain applications in general and demonstrated how to apply recommended architectural best practices.

You can learn more about the vision of Generic Transaction Interface in one of our recent blog posts covering ARK Core GTI and the reasoning behind it.
All the steps in this deep-dive are supported with working code samples and access to example implementation. Look for // source-link: comment line in the code snippets below.

This post will be followed by separate tutorials and hands-on workshops where we will build a fully working blockchain application (backend and frontend).

A Short Introduction To Custom Transactions — The Core GTI Engine

The basic premise of GTI is to provide an easy way to implement and include new transaction types in Core without the need to tediously modify more complex parts of it.

By putting some logic behind custom transaction types, we feel this is a much better and more powerful approach to develop stronger use-cases than with conventional smart contracts.

GTI was initially designed to assist our developers make implementations of new transaction types easier, maintainable, and standardized across the board.

classdg.png

What Can Be Built With Custom Transactions?

You are probably thinking:

“I can develop a custom transaction, introduce new fields, and then add them to the blockchain. Ok, sounds cool, but how does this help me develop better applications and services in general?”

Well, let me answer this:

“Most of the real-world interactions are transaction-based/event-based. Having the ability to add your custom functionality on top of existing distributed ledger technology with ease and reuse its benefits — the possibilities are endless.”

For example, we can build:

  • audit log, tracking functionalities (GDPR, ISO27001 support by default),
  • supply chain management transactions, e.g. following specific parts through receiving, manufacturing, quality assurance, packaging, distribution, maintenance, and disposal over the entire product life cycle,
  • healthcare, e.g. tracking of events, combined with storage of large medical data sets via IPFS network,
  • IoT network support, e.g. custom transaction for device registrations and storage of additional sensor data,
  • gaming support,
  • administrative role-based system governed by blockchain,

anything that is done by smart contracts, without the hassle of a complex language such as Solidity or Move

… and much more — the list is endless.

All of the above-listed examples are transactions in the real world and can be implemented with our core GTI engine.

Meaning, as a developer, you can add the new business logic to a blockchain by introducing additional custom transaction types tailored to the application. So, the next thing you need to implement is an awesome front end to support your business. Your new application becomes a light-client by default, leveraging the power of the blockchain platform in the background.

By using GTI you will be able to follow a streamlined process of creating and securing your new custom transaction type that can be deployed to any ARK based bridgechain and managed inside a separate core module (plugin).

A general overview of important classes supporting custom transaction development can be seen in the Class Diagram picture below. Abstract classes and methods in the class diagram are presented with italic text.

To develop a custom transaction type we need to implement code-contracts defined by GTI interfaces and abstract classes (the blue colored items in the class diagram above). Implementation is pretty straight forward. We override default transaction behavior and add custom business logic, by implementing the Transaction, Builder and Handler type classes (the green-colored items in the diagram above). We will implement the following three classes:

  1. {TransactionName}Transaction — introduces your new transaction type structure
  2. {TransactionName}Builder — implements payload building and signing
  3. {TransactionName}Handler — handles blockchain protocol and makes your new transaction a fully-fledged member

We will explain each of the three class types, their mechanics and purpose in the following sections. The use of the term serde throughout this document refers to the processes of transaction serialization and deserialization.



1.Implement BusinessRegistrationTransaction Class

The purpose of this class is to define and implement transaction structure, fields, serde process (transaction serialization and deserialization) and set schema validation rules. We need to inherit (extend) base Transaction class to follow GTI rules.

a.) Build Your New Transaction Structure

Your custom transaction fields must be defined inside the BusinessRegistration transaction class. They follow the rules of the inherited Transaction class. You can introduce any number of new fields and their respectful types. All new fields will be stored in the base transaction field called transaction.assets. The source-code snippet below introduces custom fields with interfaces.


export interface IBusinessRegistrationAsset {
  name: string;
  website: string;
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/interfaces.ts#L1
Enter fullscreen mode Exit fullscreen mode

The defined interface makes use of new custom transaction fields stricter and is part of the serde process. Our Public API enables searching of transactions with new custom fields by design (no API changes needed, to search within new transaction types).

b.) Implement the serde process

We need to implement custom serde methods that will take care of the serde process for our newly introduced transaction fields. Abstract methods serialize() and deserialize() are defined by the base Transaction class, and are automatically called during the serde process.

export class BusinessRegistrationTransaction extends Transactions.Transaction {
  public serialize(): ByteBuffer {
    const { data } = this;

    const businessRegistration = data.asset.businessRegistration as IBusinessRegistrationAsset;

    const nameBytes = Buffer.from(businessRegistration.name, "utf8");
    const websiteBytes = Buffer.from(businessRegistration.website, "utf8");

    const buffer = new ByteBuffer(nameBytes.length + websiteBytes.length + 2, true);

    buffer.writeUint8(nameBytes.length);
    buffer.append(nameBytes, "hex");

    buffer.writeUint8(websiteBytes.length);
    buffer.append(websiteBytes, "hex");

    return buffer;
  }

  public deserialize(buf: ByteBuffer): void {
    const { data } = this;
    const businessRegistration = {} as IBusinessRegistrationAsset;
    const nameLength = buf.readUint8();
    businessRegistration.name = buf.readString(nameLength);

    const websiteLength = buf.readUint8();
    businessRegistration.website = buf.readString(websiteLength);

    data.asset = {
      businessRegistration
    };
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/transactions/BusinessRegistrationTransaction.ts#L48
Enter fullscreen mode Exit fullscreen mode

c.) Define Schema Validation For The New Transaction Fields

Each custom transaction is accompanied by enforced schema validation. To achieve this we must extend base TransactionSchema and provide rules for the custom field validation (fields introduced in IBusinessRegistrationAsset above). Schema is defined with AJV and we access it by calling the getSchema() method inside your new transaction class, in our case BusinessRegistrationTransaction.


export class BusinessRegistrationTransaction extends Transactions.Transaction {
  public static getSchema(): Transactions.schemas.TransactionSchema {
    return schemas.extend(schemas.transactionBaseSchema, {
      $id: "businessRegistration",
      required: ["asset"],
      properties: {
        type: { transactionType: BUSINESS_REGISTRATION_TYPE },
        amount: { bignumber: { minimum: 0, maximum: 0 } },
        asset: {
          type: "object",
          required: ["businessRegistration"],
          properties: {
            businessRegistration: {
              type: "object",
              required: ["name", "website"],
              properties: {
                name: {
                  type: "string",
                  minLength: 3,
                  maxLength: 20
                },
                website: {
                  type: "string",
                  minLength: 3,
                  maxLength: 20
                },
              }
            }
          },
        },
      },
    });
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/transactions/BusinessRegistrationTransaction.ts#L15
Enter fullscreen mode Exit fullscreen mode

d.) Define BusinessRegistration Transaction TypeGroup and Type

The typeGroup + type are used internally by Core to register a transaction. Non-core transactions have to define the typeGroup otherwise Core won’t be able to categorize them. All transactions (from the release of core v2.6) will be signed with typeGroup and type. By omitting the typeGroup value, core will fall back to typeGroup: 1, which is the default Core group. We define typeGroup + type in our BusinessRegistration class, like this:

export class BusinessRegistrationTransaction extends Transactions.Transaction {
  public static typeGroup = 1;
  public static type = BUSINESS_REGISTRATION_TYPE;
  // other code ...
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/transactions/BusinessRegistrationTransaction.ts#L10-L11
Enter fullscreen mode Exit fullscreen mode

2.Implement The BusinessRegistrationBuilder Class


This class implements the builder pattern. We use it to build and sign our transaction payload. Builder class handles versioning, serde process, milestones, dynamic-fee logic and all cryptography related items (sign, multisign, second-sign, sign with and without WIF, nonce logic). The following code-snippet shows the actual implementation of the Builder class.

export class BusinessRegistrationBuilder extends Transactions.TransactionBuilder<BusinessRegistrationBuilder> {
  constructor() {
    super();
    this.data.type = 100;
    this.data.typeGroup = 1;
    this.data.version = 2;
    this.data.fee = Utils.BigNumber.make("5000000000");
    this.data.amount = Utils.BigNumber.ZERO;
    this.data.asset = { businessRegistration: {} };
  }

  public businessAsset(name: string, website: string): BusinessRegistrationBuilder {
    this.data.asset.businessRegistration = {
      name,
      website,
    };

    return this;
  }

  public getStruct(): Interfaces.ITransactionData {
    const struct: Interfaces.ITransactionData = super.getStruct();
    struct.amount = this.data.amount;
    struct.asset = this.data.asset;
    return struct;
  }

  protected instance(): BusinessRegistrationBuilder {
    return this;
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/builders/BusinessRegistrationBuilder.ts#L3-L33
Enter fullscreen mode Exit fullscreen mode

Now that we have implemented our builder class, we can use it to build new custom transaction payloads:

describe("Test builder",()=>{
    Managers.configManager.setFromPreset("testnet");
    Handlers.Registry.registerTransactionHandler(BusinessRegistrationTransactionHandler);

    it("Should verify correctly", ()=> {
        const builder = new BusinessRegistrationBuilder();
        const actual = builder
            .nonce("3")
            .fee("100")
            .businessAsset("google","www.google.com")
            .sign("clay harbor enemy utility margin pretty hub comic piece aerobic umbrella acquire");
        console.log(actual.build().toJson());
        expect(actual.build().verified).toBeTrue();
        expect(actual.verify()).toBeTrue();
    });
});
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/__tests__/test.test.ts#L7-L22
Enter fullscreen mode Exit fullscreen mode

3.Implement The BusinessRegistrationHandler Class

The previous two classes, Builder and Transaction, introduced a new transaction type, implemented the serde process, and created signed transaction payload.

In this part of custom transaction implementation, we will be handling verification and validation, following strict blockchain mechanics (consensus rules, transaction, and block processing).

By inheriting default TransactionHandler behavior we enforce existing GTI rules and provide options to implement additional transaction apply logic.


export class BusinessRegistrationTransactionHandler extends Handlers.TransactionHandler {
  public getConstructor(): Transactions.TransactionConstructor {
    return BusinessRegistrationTransaction;
  }
//...
}
Enter fullscreen mode Exit fullscreen mode

Apply logic consists of basic rules, for example, i.) check if there are enough funds in the wallet, ii.) check for duplicate transactions, iii.) if the received transaction is on the correct network (correct bridgechain), and many, many more.

We will explain GTI TransactionHandler and the role it plays in our blockchain protocol in the following sections:

a.) How To Define Your Custom Transaction Dependencies

We must define the Transaction Type registration order if our custom transaction (e.g. BusinessRegistrationTransaction ) depends on other transactions (e.g. MultiSignature )— in short, the MultiSignature transaction must be registered before ours. We define transaction dependencies by using the dependencies() method call, where we return an array of dependent classes.


export class BusinessRegistrationTransactionHandler extends Handlers.TransactionHandler {
  public getConstructor(): Transactions.TransactionConstructor {
    return BusinessRegistrationTransaction;
  }
    public dependencies(): ReadonlyArray<any> {
        return [MultiSignatureTransaction];
    }
  ...
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/handlers/BusinessRegistrationTransactionHandler.ts#L12-L14
Enter fullscreen mode Exit fullscreen mode

b.) How To Add Attributes To Global Wallets

We defined custom transaction fields and structure in Part 1. Implement BusinessRegistrationTransaction class of this article (see above).

Usually, we want to add custom properties to our global state (the walletManager class). These properties need to be quickly accessible (memoization) and searchable (indexed).

We will accomplish this with the walletAttributes() method, where we define the keys for our wallet attributes. Keys can be set during runtime by calling wallet.setAttribute(key, value) method.

The source-code below shows registering of a new wallet attribute with key=business. We set the attribute value during the bootstrap() method call. When we are done with custom wallet attribute value changes, a reindex call is recommended on the walletManager.reindex(wallet).


export class BusinessRegistrationTransactionHandler extends Handlers.TransactionHandler {
    public walletAttributes(): ReadonlyArray<string> {
        return ["business"];
    }

    public async bootstrap(connection: Database.IConnection, walletManager: State.IWalletManager): Promise<void> {
      const transactions = await connection.transactionsRepository.getAssetsByType(this.getConstructor().type);
     for (const transaction of transactions) {
      const wallet = walletManager.findByPublicKey(transaction.senderPublicKey);
      wallet.setAttribute<IBusinessRegistrationAsset>("business", transaction.asset.businessRegistration);
      walletManager.reindex(wallet);
    }
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/handlers/BusinessRegistrationTransactionHandler.ts#L25-L29
Enter fullscreen mode Exit fullscreen mode

c.) Tapping Into the Transaction Bootstrap Process

*Bootstrap process is run each time a core node is started. * The process evaluates all of the transactions in the local database and applies them to the corresponding wallets. All of the amounts, votes, and other custom properties are calculated and applied to the global state — walletManager. Since our new custom transaction BusinessRegistrationTransaction follows the same blockchain mechanics, we only need to implement relevant (see code snippet below) apply methods defined by the TransactionHandler interface.

export class BusinessRegistrationTransactionHandler extends Handlers.TransactionHandler {
  // ...

  public async applyToSender(transaction: Interfaces.ITransaction, walletManager: State.IWalletManager): Promise<void> {
    await super.applyToSender(transaction, walletManager);
    const sender: State.IWallet = walletManager.findByPublicKey(transaction.data.senderPublicKey);
    sender.setAttribute<IBusinessRegistrationAsset>("business", transaction.data.asset.businessRegistration);
    walletManager.reindex(sender);
  }

  public async revertForSender(transaction: Interfaces.ITransaction, walletManager: State.IWalletManager): Promise<void> {
    await super.revertForSender(transaction, walletManager);
    const sender: State.IWallet = walletManager.findByPublicKey(transaction.data.senderPublicKey);
    sender.forgetAttribute("business");
    walletManager.reindex(sender);
  }

  public async applyToRecipient(transaction: Interfaces.ITransaction, walletManager: State.IWalletManager): Promise<void> {
    return;
  }

  public async revertForRecipient(transaction: Interfaces.ITransaction, walletManager: State.IWalletManager): Promise<void> {
    return;
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/handlers/BusinessRegistrationTransactionHandler.ts#L92-L113
Enter fullscreen mode Exit fullscreen mode

d.) How To Implement Transaction-Pool Validation

The Transaction Pool serves as a temporary layer where valid and verified transactions are stored locally until it is their turn to be included in the newly forged (created) blocks.

Each new custom transaction type needs to be verified and accepted by the same strict limitation rules that are enforced for our core transactions. We need to implement canEnterTransactionPool() method (see source-code snippet below) to follow the rules and execution structure. The method is called from the core.

export class BusinessRegistrationTransactionHandler extends Handlers.TransactionHandler {
  // ...
  public async canEnterTransactionPool(
    data: Interfaces.ITransactionData,
    pool: TransactionPool.IConnection,
    processor: TransactionPool.IProcessor,
  ): Promise<boolean> {
    if (this.typeFromSenderAlreadyInPool(data, pool, processor)) {
      return false;
    }

    // TODO: check the link for more validation options
    return true;
  }
}
// source-link: https://github.com/kovaczan/custom-transaction/blob/167bcbd5201282a6d679d9d571eed00bbc1df57c/src/handlers/BusinessRegistrationTransactionHandler.ts#L55-L91
Enter fullscreen mode Exit fullscreen mode

4.Registration of a Newly Implemented Transaction Type Within Core

**You made it. **The final step awaits, and it is the easiest: registration of the newly implemented BusinessRegistrationTransaction type. To accomplish this, we need to get access to the core-transactions handler and call registerTransactionHandler() method (see code below).


async register(container: Container.IContainer, options) {
    container.resolvePlugin<Logger.ILogger>("logger").info("Registering custom transaction");
    Handlers.Registry.registerTransactionHandler(BusinessRegistrationTransactionHandler);

  }
// source-link: https://github.com/KovacZan/custom-transaction/blob/master/src/plugin.ts#L11-L12
Enter fullscreen mode Exit fullscreen mode

Your custom transaction type implementation is now COMPLETE. A fully working example is available for you to examine, learn and download here.

This example is implemented as a core module (plugin). You can learn more about core modules at https://docs.ark.io/tutorials/core/plugins/how-to-write-a-core-plugin.html and is using develop branch of the Core to achieve the above results (upcoming v2.6 Core).

How To Access New Transaction Types via Our Public Interfaces

Our newly implemented transaction type becomes a full member of a core node after the registration call — meaning we can query it via existing Public API interfaces, after the plugin is deployed on the blockchain.

You can read more about our Public API here: https://api.ark.dev.

Seamless Integration With ARK Core:

We provide twelve (12+) different programming language implementations of our API, all accompanied by full cryptography protocol implementation. Simply install the SDK of your choice and start interacting with the blockchain.

For more information about our SDKs (REST API and crypto) refer to https://sdk.ark.dev.

Secure JSON-RPC client:

We also provide a JSON-RPC compliant package, targeting exchanges and other trusted execution environments. JSON-RPC client is meant to run inside a trusted environment.

For more information about secure JSON-RPC client refer to https://exchange.ark.dev/json-rpc/getting-started/.

Conclusion

After learning the best practices and architectural approaches in Part 1 of this series , we took a deep-dive into custom transaction type development with our Core GTI technology. We learned how to:

  • Implement a new transaction type structure
  • Implement a new custom transaction builder class
  • Implement a general transaction handler that hooks our newly created transaction type with the blockchain protocol
  • Use existing API interfaces to interact with core blockchain and new transaction types.

Your newly implemented transaction type can now be packed into a core module and distributed to any ARK technology-based bridgechain (API and protocol compliant).

This series will be followed by separate tutorials and hands-on workshops where we will build a fully working blockchain application — backend and frontend. Stay tuned for exact dates and webinar registration links, and get involved!

GET INVOLVED

Here’s a quick list of what your next steps might be to get involved with ARK:

Top comments (1)

Collapse
 
dasasa profile image
Fozla •

The success of your business depends on many factors, but security is one of the most important pessimistic . That is why you should not skimp on services that guarantee cybersecurity at an almost priceless level. I wish you good luck in finding and choosing a good business service option that will take care of the safety of your data and ensure the success of your enterprise!

Read next

dm8ry profile image

Python code that generates a stock price chart for the last n days.

Dmitry Romanoff -

jt_ziolo profile image

Creating a Global .gitignore File as an Extra Line of Defense Against Bad Commits

JT Ziolo -

mspilari profile image

Fullstack app: Deploying the Fullstack Application on Render with Docker

Matheus Bernardes Spilari -

mnkow profile image

From Monolith to Monorepo: A Next.js Migration Story

Michal Kowalkowski -