Hive Stream Builder: set up a hive-stream app in your browser and download the code

If you haven't come across it, hive-stream is my Node.js library for building apps on Hive. It's designed to be the ultimate starter library for Hive apps. It streams blocks, runs your contract code when someone calls it with a transfer memo or custom_json, and gives you everything you need to respond, whether that's a payout, a refund or a vote. People use it for dice sites, game tournaments, tipping bots, token exchanges and custody bridges. It comes with 45 ready-made contracts, SQLite, MongoDB and PostgreSQL adapters, a CLI, and since the last update, an offline testing kit.

The CLI (npx hive-stream new) gets you a starter project, but there's still a fair bit to do after that. You need to work out which built-in contracts you want and what their options are, write a zod schema for each of your actions, add guards to anything that takes money and set up your bot subscriptions. I built Hive Stream Builder to take care of that part.

Hive Stream Builder is a web app where you configure a hive-stream project and download it as a zip. Everything happens in your browser. There's no backend or account, and it never asks for your keys. You add those to .env after downloading.

The settings are on the left and the generated project is on the right. The code updates as you go, so you can see what each option changes before you download anything.

Starting point and settings

First you pick a starting point. The options are the same templates the CLI has (Minimal, Game, Exchange, Social, Blog, Token & NFT and Assets & Tickets), and the download starts from the exact files the CLI would write. You also choose a database (SQLite, MongoDB or PostgreSQL), set your app's Hive account and decide whether to turn on the HTTP API, which serves contract state, events and a /health endpoint on port 5001.

The Streamer page covers how your app follows the chain. You can process irreversible blocks only, which is the default and what you want for anything involving money, or follow the head block for lower latency. You can also set how often the block position gets saved, turn on duplicate protection so a replayed block never runs the same action twice, and choose what happens when an action fails: skip it, retry and then stop, or stop straight away. If you tick any hooks like onError or onFork, you get typed stubs for them in src/hooks.ts. Only settings that differ from the defaults are written out, so the config doesn't get bloated.

Built-in contracts

Every contract that ships with hive-stream is in the catalog, sorted into categories like gambling, games, finance, governance and tokens. The list is pulled from hive-stream/catalog, so new contracts show up in the builder as soon as they're added to the library.

Once you add a contract you can fill in its options and add guards. Guards let you choose which accounts are allowed or blocked, which assets it accepts, minimum and maximum amounts and a rate limit per account. You can also pause a contract while you do maintenance.

Custom contracts

For your own contracts, you add actions and choose how each one can be called. That can be custom_json, a transfer memo, a schedule, a recurring transfer or one of the escrow operations. You can require the active key for custom_json calls, and you define the payload fields, which become a zod schema so bad payloads get rejected before your code runs. You can also add SQL tables and scheduled jobs. Scheduled jobs run on block time, so they behave the same during a replay as they do live.

Each contract is written to src/contracts/<name>.contract.ts along with a call spec your frontend can import. It also gets a test that runs every action through hive-stream/testing, the offline testing kit I wrote about in my last Hive Stream post. So the contract you download comes with tests already written.

Bots

Bots are rules that react to things happening on chain. Each rule has a trigger, optional conditions and one or more actions. Triggers include transfers, custom_json, posts, comments, votes, Hive Engine actions, escrows and follows. Actions can send HIVE or HBD, refund the sender, send Hive Engine tokens, upvote or write to the log. Each trigger only lets you use the fields it actually has, which means the generated src/bots.ts always compiles.

Call builder

Once your contracts are done you still need to call them from a frontend. In the call builder you pick a contract and an action and fill in the payload. It gives you the transfer memo or custom_json operation, the hive-stream/client code, and a Hive Keychain call you can paste into your site. It checks the payload the same way the contract will, and it never broadcasts anything.

Testing the generated code

Generating code is only useful if the code actually works, so the repo has a script for checking it. npm run verify:generated generates a project for every template and database combination, a project that uses every feature on each database, and one that registers every built-in contract. It then runs tsc --noEmit and the Jest tests on each one against the hive-stream version it pins. It's meant to be run whenever a generator changes or hive-stream gets a new release, which stops the builder falling behind the library.

Saving and sharing

Your project is saved in your browser as you work. You can also copy a share link, which has the whole configuration in the URL, or export it as YAML and import it again later.

You can try it at vheissu.github.io/hive-stream-ui and the code is on GitHub. If it ever generates something that doesn't compile, open an issue with your share link and I'll be able to reproduce it.