# 🐝 Meet WorkerBee: The Easy Way to Build Smart Blockchain Bots

Welcome to WorkerBee — the library that makes building powerful bots operate on the Hive blockchain as easy as programming a web page! </>

We already announced this library in several of our articles in the past: [here](https://blog.openhive.network/hive-139531/@small.minion/hive-application-development-guide) and at [initial rough presentation of our tools](https://blog.openhive.network/hive-139531/@thebeedevs/how-to-distinguish-a-fly-from-a-bee). For one and a half years our developers (mostly using this library - our hope is to see your use cases too) have proven that the initial version works well (it was used as a heart of [optimistic UI implementation in Denser](https://javascript.plainenglish.io/what-is-optimistic-ui-656b9d6e187c)).

Moreover, we have a few ideas how to simplify the use and provide you with "ready to go solutions" for very common usecases without losing any ability to process completely custom one.

Our answer to your common needs are predefined processing primitives, but allowing mixing them according to your needs as well as still providing ability to use custom bot trigger conditions.

So whether you want to track new posts, watch account changes or react to blockchain events, WorkerBee takes care of the hard stuff so you can focus on **what** ✨ you want your app to do, not the gritty details of **how** 🧠.

 ![ai-bee.png](https://images.hive.blog/DQmP7qKF1foYrtCNMCGNUbe9E273LFnuSXtzhooATMsNdkZ/ai-bee.png) 

## 👉 Why Use WorkerBee?

**WorkerBee** is designed for every programmer, not only for blockchain developers! Here is what makes it special:

- **No More Endless Loops! 🔄** 
Just say what you want to listen to - WorkerBee does all the waiting and event handling behind the scenes.

- **No Blockchain Headaches! 🧩** 
Forget complicated APIs and coding tricks. Write logic much like you would on regular web apps (think: “When a new post appears by Alice, send me a ping!”).

- **Keep Your Sandbox Clean 🧼**
WorkerBee shields your code from the messy details of blockchain data, so your app stays flexible and easy-to-maintain.

- **One Interface, Many Sources 🗃️** 
Switch from live blockchain data to a historical database or new data source (e.g. SQL) - all without changing your app’s logic!

- **Easy to Expand 📈** 
Start simple but add new events, rules, or channels as your needs grow.

- **Fully typed ℹ️**
Library APIs have well defined types and functional interfaces with special support for IDE IntelliSense

 ![wb-fully-typed.gif](https://images.hive.blog/DQmY6Ka3XLJ3BPEw4NqZYqfhuhBokw8ER2EknoTFjw3Kw7s/wb-fully-typed.gif) 

## 🕹️ What Can You Build with WorkerBee?

- 💬 Automatic reward bots for blog comments,
- 📅 Custom notifications for changes in your favorite accounts,
- 📊 Powerful monitoring dashboards,
- 📢 Alert/response bots for blockchain events,
- 🌎 Web2 social media integrations,
- 🎮 On-chain Games,
- ...and much more 😎!

## 🧱 Bot building blocks

To provide a flexible way of creating the triggers tied to some blockchain events, the library offers a set of functional primitives being specialized to the features offered by Hive blockchain. For example, if you want to watch new posts written by your friend, the WorkerBee allows you to use `onPosts(author)` condition which completely isolates you from low level blockchain operations and also from the knowledge how to gather them.

Such building blocks (called also as *condition primitives*) can be joined into more complex expressions by using `or`/`and` logical operators which allow you to build custom "logical expressions" matching your data processing criteria.

Involving given condition primitive, automatically passes gathered data (e.g. post permlinks) to your callback function.

We also allowed forcing the library to additionally collect and pass to your callback some different data collected at runtime - to use this feature you should call special methods called `providers` which on demand collect, transform and **provide** data to your callback function when it should be called after satisfied evaluation of defined condition.

For example this code
```ts
   workerbee.observe.onBlock().provideAccounts("account1", "account2").subscribe({
     next: (data) => {
       console.log("Account 1 data:", data.accounts["account1"]);
       console.log("Account 2 data:", data.accounts["account2"]);
     }
   });
```
allows gathering data specific to given accounts and passing them to your callback. What is important - you do not need to know anything about any API needed to do it.

To make it work, the library internals are built by using a set of objects having different responsibilities:

- collectors - their role is to handle a communication layer between blockchain and workerbee library. Current implementation is based on RPC API calls, but its abstract design allows switching them in the future for example to SQL based one.
- filters - such a class of objects is responsible for gathering data from collectors and evaluating the condition specific to given filter class
- data providers - their function is to gather data from collectors, transform them into official WorkerBee interface to be finally passed to your callback.

The last important thing is the finalization of the observer object previously defined from the set of condition and provider primitives. It happens once you call `subscribe` method.

Further chapters contain library architecture description in great technical detail, including data flow performed during each processing cycle.
 
## 🛠️ Data Flow at a Glance

WorkerBee consists of multiple layers of data analysis:

`Blockchain Data` ⛓ → `Collectors` 🛒 → `Data Evaluation Context` 🧠 → `Filters` 🔎 → `Providers` 🚚 → `Your Observer Callbacks` 🤳

1. Blockchain Data ⛓ - The library operates on the blockchain data on an abstract level - it can fetch data from multiple sources, such as JSON-RPC (hived Node) API, REST API, HAF SQL, etc. It is worth mentioning that at the moment all the features offered by WorkerBee need to work only **consensus** node.
1. Collectors 🛒 are strictly connected with *Classifiers* which enforce an expected collector result. In other words the *Classifier* identifies collector implementation which can provide a given class of data (and separate collector implementations can be provided for requested classifier by using a Factory object pattern). This way an user can fetch data from any supported source without changing anything in its code. A set of needed classifiers (and chosen collectors) is determined by requested Filters and Data-Providers described below. The collector data acquisition is executed only on demand to avoid wasting a computational power until their execution is needed.

1. The **Data Evaluation Context (DEC)** 🧠 is the brain: It manages dependency injection, caches, shared store, cycle timing and orchestrates everything behind the scenes. And due to **Smart Cache** we can get the data we want, only when it is actually needed by the framework and limit the API calls when they can be reused. The `DEC` is central hub of communication layer and allows sharing **cached** data between filters & collectors which want to consume them and collectors being responsible for gathering them.

1. Filters 🔎 run all in parallel with predefined conditions. Upon listener creation, a user can define advanced `AND`/`OR` logic between filters, extending their functionality and creating complex expressions. There is implicit `OR` association -  using two subsequent filter building blocks involves `OR` condition. For example:
   ```ts
    workerbee.observe.onAccountsBalanceChange(false, "username").onAccountsMetadataChange("username").subscribe({
      next: () => {
        console.log("Someone is messing with @username account !!!");
      }
    });
    ```
    The WorkerBee filter implementation supports Short Circuit Evaluation scheme so it does not waste time on waiting for all the filters.

1. Providers 🚚 evaluate only when at least the filter associated to the whole observer object passes. Providers also run in parallel, transforming the collected data to public WorkerBee object model and passing it to the user callback.

1. Your observer callback 🤳 runs with data normalized by providers. This function is also async, which means the main loop does not wait for it in order to execute next iteration. The result is that you can instantly react to blockchain changes and broadcast transactions without worrying about loosing other live data 👀

 ![DEC-cycle-chart.png](https://images.hive.blog/DQmaKEVgP1vCPdYzhYCmu8AMz5NfEHy6ake7cgYBKYVGpHF/DEC-cycle-chart.png) 

## 🌄 Real-Life Scenario: Blog Post & Account Tracking

Let us say your bot needs to monitor blog posts and comments by Alice, and manabar load of Bob's in order to vote for Alice's content

To achieve this we need to use the following filters & providers:
- **Filters**
  - `PostFilter`: triggers when bot detects new posts authored by Alice,
  - `CommentFilter`: fires when Alice made some new comments,
  - `AccountFullManabarFilter`: will match when Bob's account manabar load exceeds specified percent
- **Providers**
  - `PostProvider`: retrieves data specific to all detected Alice's posts,
  - `CommentProvider`: gathers data of all new Alice's comments,
  - `ManabarProvider`: receives Bob's manabar value

Further part of this article shows the code doing it (please do not be disappointed by the small amount and simplicity of the attached code - it was our intention to allow simple coding of complex things as described above - we hope you will appreciate it :-) ).

 ![gantt.png](https://images.hive.blog/DQmTzGCbcxGt3djuQ3adHQ96ap2YtxCQ48N9xXxpSygh1W2/gantt.png) 

### 🔃 A Typical Notification Cycle

As we have previously promised, WorkerBee eliminates a need to write its own *mainloop* to trigger the whole bot machinery - the library performs it in its own specific way - what has technical and performance related explanation. This process depends on current evaluation phase. Let say we have to process thousands of past blocks to get posts created for the last week - it means that your bot should consume data as fast as it can 🚀, because there is nothing to wait for - all requested blocks already exist (and thanks to OBI they are usually written in a rock 🪨 ). Things seem to be different when a bot enters live sync (reaches blockchain head). Without special progamming techniques, it can start naive API spamming process for periodic (usually too frequent) lookup for new data. The workerbee library (as its natural equivalent: 🐝 ) is smart: since it knows query context, it can create massive queries (and data processing) for past data and periodic (time triggered - 2s based) for live sync. Another big helper in this process is abstract layer specific to *Collectors* which sometimes have different implementation for past and live phases. Well done object oriented design always brings good benefits :-)

So let us analyze the role of all actors involved into work during single notification cycle (let say once per block):

- Data Evaluation Context: **DEC** 🧠 initializes and injects collectors required by filters and providers (including their **dependencies**)
- Concurrently 🔎:
    - `PostFilter` requests `OperationCollector` via DEC and fetches data from the blockchain. `OperationCollector` needs `BlockCollector`, which needs `DGPOCollector` (dynamic global object properties collector). It finds Alice's post and matches.
    - `CommentFilter` requests `OperationCollector`, and since `PostFilter` already requested it, it only waits for the fullfilled cache in DEC and does **not** call the API again. It searches for Alice's comments, but is interrupted by `PostFilter` match, which finished its own work earlier and due to `short circuit evaluation` scheme cancelled other evaluations.
    - `AccountFullManabarFilter` requests `RcAccountCollector`. It fetches RC data of Bob's, but it is also cancelled by `PostFilter` match.
- Concurrently 🚚:
  - `PostProvider`: Retrieves all new Alice's posts from the cache.
  - `CommentProvider`: Retrieves all new Alice's comments from the cache.
  - `ManabarProvider`: Retrieves Bob's manabar load from the cache
- **End Result:** Your observer receives `{post, comment, rc data}` – ready to act! 🤳

 We will publish soon the explanation of the differences between collectors (and why we need to have so many of them) :-)

## 🚀 WorkerBee in Action: Stablitity, Efficiency and Performance

### Stability

As mentioned before, our library introduces its own typed data layer. It means that your bots start to be independent on direct blockchain API calls (which are changing over time). Data provided based on such calls are wrapped by WorkerBee library to provide call results in normalized WorkerBee format. Moreover, some of them need to use special API call techniques to hide errors e.g. specific to `too many requests`. So taking care of network call errors is also moved from your code into common implementation of the library communication layer.

### Performance and efficiency

To get desirable performance results, out library introduces a few optimization aspects. Most important ones cover concurrency (asynchronuous execution) and caching specific to single notification cycle. Because of encapsulation, all such techniques are hidden from a client code. Below you can see greater details specific to information gathered during testing and benchmarking of the library.

####  WorkerBee’s Built-In Caching Delivers 🛵

- At least **50% fewer API calls** in real-world multi-filter scenarios!
- **Consistent Data:** Every component works from a single state snapshot per cycle.
- **Smooth Scaling:** From average of 6 to 3 API calls per cycle in real workloads.
- **Linear Complexity:** Dependency chains do not explode resource usage.

#### Cache Invalidation Strategy 🎯

- **Per-Cycle**: Cache is completely cleared at the start of each notification cycle
- **Atomic**: All data represents a consistent blockchain state snapshot
- **Dependency-Safe**: Collector dependencies always see the same cached data
- **Memory Efficient**: No long-term memory accumulation from caching

#### DEC Caching Performance Example Benchmark 💫

|                    | WorkerBee without DEC Cache 😭 | WorkerBee with DEC Cache 😎 | Naive implementation 🧙‍♂️ |
|:------------------ |:------------:|:-------------------:|:---:|
| API Calls per cycle **\***  |      6      |         **3**          | 10 |
| Network Latency    |    500ms     |       **250ms**         | 830ms |
| Throughput         |      –       |       **+2×**         | -0.7x |
| Node Load          |     High     |       **Low**           | Very High |
| Intelligence       |     +5       |       **+420**          | -9001 |
| Stamina | +1 | **+42** | -9001 |

**\*** - A Number of calls calculated based on the scenario of operation filter, 3 accounts filter and operation & account provider

## 🧰 Core Patterns & Architecture

WorkerBee leverages proven design patterns for clarity, flexibility, and speed:

- 👀 **Observer Pattern:** Event-driven, just like front-end UIs.
- 🚸 **Dependency Injection:** Clean orchestration and loose coupling between data collectors and business logic.
- ♟️ **Strategy Pattern:** Factories swap data sources (RPC, SQL, etc.) on demand.
- 🏄 **Fluent API:** Build logic by chaining calls, à la jQuery or modern Node.js libraries.
- 🔛 **Type-Safe Interfaces:** Compile-time safety and great DX.
- ♻️ **Fine-Grained Caching:** Every component shares the most recent data snapshot for max performance.

## 📦 High-Level APIs (Think Query-Language Simplicity)

The WorkerBee interface aims to be as powerful as SQL, but as friendly as jQuery. You build what you want to see:

```js
bot.observe
  .onPosts("alice")
  .onAccountsFullManabar("gtg")
  .subscribe({
    next({ posts }) {
        for(const { permlink } of posts.alice) {
            console.log(`Alice created post "alice/${permlink}"`);
            console.log("Voting as gtg as it has full manabar...");
        }
    },
    error: console.error
  });
```

 ![filters-graph.png](https://images.hive.blog/DQmb6D9bJbdn8gHdRtcjBpxjLPqtNXKHPnzaMKnaTnHbdbJ/filters-graph.png) 

## 🚧 On-going work

We are currently working on improving the past data collection and adding new filters & providers. 🎨

Thanks to that, you will be able to react to even more events on blockchain! ⚛️

We would love to hear your feedback so we can make our software even better than it already is! 😎

## 🔜 Future of WorkerBee

- 🛢️ SQL Integration
- 🛌 REST API support
- 🐍 Python implementation of WorkerBee
- 🤖 Implementing new bots
- 👨🏻‍💻 Spreading the use of WorkerBee across all automation applications!

## ✅ WorkerBee is already in production!

**Optimistic UI** feature in [Denser](https://gitlab.syncad.com/hive/denser) allows visualizing and tracking the state of blockchain transactions specific to UI actions like votes, comments:

 ![like-like-denser.gif](https://images.hive.blog/DQmXuovZNmWiVGigrVW7jsGbGhobR8tNd6VkN5E4ivyk85c/like-like-denser.gif) 

You guessed it right - It's WorkerBee-powered! ⚡ - WorkerBee awaits the confirmation of the vote operation in the blockchain and triggers UI updates. All such features have been achieved just by calling to overloaded `broadcast` method which additionally does such tracking - so **again we have oneline code implementation !!**.

You can try it yourself - please go to [Denser blog](https://blog.dev.openhive.network) with revolutionary [HiveSense AI Search](https://blog.dev.openhive.network/hive-139531/@thebeedevs/hivesense-have-you-heard-about-new-ai-search-in-hive)! 📚

Besides, we also created multiple small bot applications integrating Hive platform with other services like RSS, some chats... We will describe them in more details in our next post soon.

## ⚡ Ready to Try WorkerBee?

Whether you build blockchain bots, analysis tools or want a better event architecture – start simple, scale up, and never worry about main-loop spaghetti or wasted API calls again.

> **WorkerBee:** All the power of blockchain events - none of the hassle.

### 📝 Getting Started

Please check out the [WorkerBee Documentation](https://gitlab.syncad.com/hive/workerbee/-/blob/13b88274e585e53dcbc5b861bfc556e346e7769f/README.md) 📡!

WorkerBee is your friendly helper for blockchain bots — **fast, efficient, and super easy to use.** 
Let it do the buzzing while you focus on building something amazing! 🧑🏻‍💻

Happy coding and see you soon again !!!