Introducing Nimble

A solid bitcoin library is the foundation for any bitcoin app or service, and also for Run. Today we’re pleased to announce nimble - a practical everyday JavaScript library for BSV. Weighing in at just 64kb, you can think of it as smaller, faster, and more modular version of bsv v1 library that you’re probably already using. It works all major browsers and NodeJS 10+ and has a lower-level API for advanced developers too. And it’s open source too! You can start using it today.

Getting started

npm install @runonbitcoin/nimble

or

<script src="https://unpkg.com/@runonbitcoin/nimble@1.0.7"></script>

Let’s see some examples

Create and sign a transaction

1
2
3
4
5

const transaction = new nimble.Transaction()
   .from(utxo)
   .to(address, amount)
   .change(changeAddress)
   .sign(privateKey)

Generate new keys and address

1
2
3

const privateKey = nimble.PrivateKey.fromRandom()
const publicKey = privateKey.toPublicKey()
const address = privateKey.toAddress()

Decode transactions scripts

1
2
3

const transaction = nimble.Transaction.fromString(hex)
    
transaction.outputs[0].script.chunks[0].buf

Hash arbitrary data

1

nimble.functions.sha256(data)

Anything else?

We’re happy that this is the first piece of the Run SDK to be open-sourced with more to come.

Check it out on the github: https://github.com/runonbitcoin/nimble

And we welcome your contributions or ideas for improvement! Thanks.

3D Models and Audio Jigs!

We have the pleasure to announce that we now support Jigs containing 3D models and audio in our explorer!

In order to do that, we are going to be using the metadata object as explained here.

So, in a few words:

• for Audio files, you could just set a b protocol uri (b://) that references the file
• for 3D models is the same: use a b uri that references the file. The only clarification is that for now, we only support 3D models in GLB format.

Formats

Audio files

For audio files, the supported formats are WAV, MP3 and OGG. All browsers support those formats except Safari that doesn’t support OGG, and Edge, that doesn’t support WAV and OGG previous version 79.

Why GLB format for 3D models?

There are plenty of formats to represent 3D objects. GLB is often used for 3D NFTs and other renderings on the web because it has all the information needed (like the lighting, the textures, the cameras, etc.) stored in just one binary file. It’s the standalone version of the GLTF format, which contains the same information but spread across several files and uses JSON to encode it. So we use GLB not only for its convenience, but because it also takes less space (~33%) and is faster in loading times.

Ok, great! Do you have an example?

Yep, here is a link to a post in which we explain how to upload files to the blockchain using our brand-new tool called EasyB.

Here are some jig examples if you want to play with them directly in the explorer:

• 3D Model Jig: d09836f2ed5a2788560020ac30b71868352706da96f60363e685a48a5401f146_o1
• Audio Jig: 6cd8ba6b81cf157eb6f48592db9fe0706c60529adf6c83fc9a3fdef465292603_o1

If everything is alright, for example, a 3D model should look like this:

And that’s it! See you in the next post!

Advanced jig metadata

Something nice about jigs is that they can carry metadata. Metadata is all the useful information for displaying and describing jigs to users, such as names, images, 3D models, audio, and more. Wallets and exchanges read this information to make better user experiences.

Most of the time people store this media data directly on the BSV blockchain. The standard way to attach media as metadata on jigs is by using B files. B is a simple protocol to upload binary data (files) to the BSV blockchain.

Any B uri can be used as metadata for a jig. For example:

1
2
3
4
5
6
7
8

class Dragon extends Jig {
  init (name, imageUri) {
    this.name = name
    this.metadata = { image: imageUri } 
  }
}

const aDragon = new Dragon('pepe', 'b://92b00456e0072ad51a97fe6ff31ba59079128529cb5b247eea5588610cb3d493')

But uploading B data is not always easy.

Introducing EasyB

EasyB is a CLI tool and micro library to manage B transactions. EasyB removes all the complexity around building, signing, validating and publishing transactions. The only thing needed to publish files using easy B is a little bit of BSV to fund transactions, and the rest is managed by the library.

EasyB can be used in 2 different ways. As a CLI tool, easy-b is easy to integrate inside bash scripts, deployment pipelines, etc. But EasyB can also be used as a standalone library inside nodejs, which offers tons of flexibility to integrate inside any kind of custom logic. Let’s see an example of both of these usages:

cli

1
2
3

export PURSE_WIF=<my-funded-wif-key>
npx @runonbitcoin/easy-b publish ~/Images/dragon.png
# output: Success! 92b00456e0072ad51a97fe6ff31ba59079128529cb5b247eea5588610cb3d493

And then with the txid:

1
2

// ...
const aDragon = new Dragon('pepe', 'b://92b00456e0072ad51a97fe6ff31ba59079128529cb5b247eea5588610cb3d493')

from nodejs

Or you can directly use it from nodejs. You just need to install it:

1
2
3
4
5

npm i --save @runonbitcoin/easy-b

# or

yarn add @runonbitcoin/easy-b

And then use it:

1
2
3
4
5
6
7
8
9

const { BFile, publish, networks } = require('@runonbitcoin/easy-b') 

const main = async () => {
  const bFile = await BFile.fromFilePath('~/Images/dragon.png')
  const txid = await publish(bFile, networks.MAINNET, process.env.PURSE_WIF)
  const aDragon = new Dragon('pepe', `b://${txid}`)  
}

main()

EasyB is already published and ready to be used here. If you found any issue or have suggestions you can publish them as an issue on github.

Introduction

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:

1

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:

1

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:

1
2
3

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:

1

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:

1

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.

Performance

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:

1

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.