Run-DB Overview


Today, we’re excited to announce Run-DB — a new database and indexer for all your RUN transactions and their jigs!

Run-DB solves the most important problem affecting Run developers today: loading jigs quickly with predictable performance.

To summarize, there are two ways Run is able to load a jig. Either Run can go to the blockchain and download potentially hundreds or thousands of transactions before executing them with the virtual machine, just to calculate the state of a single jig, or Run can just read the jig’s state directly from a cache. Loading a jig from the cache, even for a single transaction, will always be faster.

But loading from a cache also needs caching infrastructure, both to store states and to calculate them. You were always able to build this infrastructure yourself using the Run SDK and its APIs, and several developers with heroic abilities have done so, but for the rest of us, there’s a simpler solution: Run-DB — Your personal state server.

Getting Started

The code for Run-DB is fully open-source and under the MIT license. Clone the Github repository today or install from NPM. You can fork it, fix it, or open issues — whatever you need.

Using Run-DB is simple. There’s no requirement to operate a database server, or to configure docker, or to run a node. Just run:

env API=planaria env PORT=8000 npm run start

… and you’ll see RUN transactions start to download immediately from either Planaria or MatterCloud. These transactions will be executed and their states will be stored into a local SQlite database, run.db. You can begin making queries on them right away:

curl localhost:8000/unspent?address=1Kc8XRNryDycwvfEQiFF2TZwD1CVhgwGy2

Next, you’ll want to hook Run-DB up to your application that uses Run. As of v0.6.18, the Run SDK provides a new plugin called RunDB that you can use as your cache. Here’s how to hook it up:

const cache = new Run.plugins.RunDB('http://localhost:8000')

const run = new Run({ cache, client: true, trust: ['cache'] })

Finally, client mode is fully functional now. When you put Run into client mode, you are telling Run to use Run-DB as your source of truth, which makes your application performance very predictable. Run will only use the blockchain APIs when broadcasting a transaction or querying your purse UTXOs, but all your jigs, even those in your inventory, will load from Run-DB.

For your transactions

Run-DB lets your application store and execute only those transactions you care about.

We believe in the long run that this is the best way for apps on bitcoin to scale — by individual apps building up their own private database of transactions that are relevant to them. This will create efficient Mandala Networks between miners, services, applications, and users, and it is likely that someday applications will even start sharing Run-DB transactions peer-to-peer.

In its first iteration, Run-DB downloads all RUN transactions, but it will only execute transactions you trust. Transactions where you deployed or upgraded code need to be trusted. You can check your current trust list via:

curl http://localhost:8000/trust

Run-DB ships with a small default trustlist, but you can tell it to trust any code you know is safe:

curl -X POST http://localhost:8000/trust/<txid>

You may wonder why a database even necessary when we have Bitcoin? There will always be a need for apps to organize, process, and filter the raw data on Bitcoin, to make it accessible quickly for their users. If your server ever crashes, Bitcoin remains the source of truth.


Executing basic token transfers at 100+ tx/sec

Performance is important. We’re here to scale.

On a standard developer laptop, Run-DB will easily index basic token transfers at more than 100 transactions per second. This would support apps having more than 8M transactions per day, more than Ethereum’s daily transaction volume, and an order of magnitude more transactions than the most popular blockchain app at the moment.

But that’s not enough. See Run-DB never really hits a scaling limit.

In contrast to other smart contracting blockchains which are account-based and use global state, the RUN protocol only uses local state. All your jigs are local to the transactions they are updated in. This means RUN transactions, like basic Bitcoin transactions, can be infinitely sharded and parallelized, and that’s exactly what Run-DB does.

Run-DB creates 4 worker threads by default to index transactions, but you can easily bump this up if you have the horsepower:

env WORKERS=16 npm run start

In the future, Run-DB will also be able to distribute its worker threads across multiple machines, each executing your transactions in parallel.

What else you can do

Once you dive in, you’ll discover there’s a lot more you can do with Run-DB than just load jigs quickly.

You can:

  • Make queries about balances, volume, and history
  • Blacklist individual transactions and their descendants
  • Exchange transactions peer-to-peer with other services efficiently
  • Analyze app usage from other programming languages
  • Host a public Run-DB server for others to connect to

And more.

Several projects are already using Run-DB today. RelayX is using it in their DEX to surface orders, and The Mornin’ Run and BSV Token Explorer are both using it to track tokens. If you create something fun using Run-DB, give it a shout-out to inspire others!

For more information about configuring Run-DB, making custom queries, and or general usage, check out the Github README.

Then, if you get stuck, come hang out in the run-sdk channel of the Atlantis Slack.