Tutorial: Learn to code with jigs that run on bitcoin

A jig is an interactive object you can run on bitcoin. People interact with jigs by calling methods on them. And, jigs also interact with each other. These interactive objects allow you to build almost anything you can dream up on bitcoin. You might create tokens, contracts, and interfaces. Jigs can power document signing, logistics, even voting in elections. The most fun of course will be video game items and lifelike digital pets!

Many developers use object-oriented programming to write their apps. Imagine the classic example of a car. A car has wheels and an engine–that’s basically the definition of a car. But specific cars have attributes like red color. In programming, we call the specific cars, instances. So you have a class definition of Car and then potentially many instances, carA, carB, carC, driving around in the world.

With that short introduction, you’re starting to get a feel for how you build jigs. So let’s get going.

Getting Started

You should already have the latest version of run as a ZIP archive. Open getting_started.html in the Chrome browser.

Arrange the browser window side-by-side with this tutorial by having two windows up or by arranging full-screen windows on separate desktops that you can slide between.

Exploring jigs

To get a feel for jigs, click Explorer in the top right of the page in the nav bar:

Search for the address: 175vV9raKEeBA167PtoP4gDSyyG5ngf8bf. This bitcoin address holds three jigs, and you can also see when they were last updated:

Locate the first jig in the list, Dragon, and click on the last updated time. Notice that the search field has been changed to a transaction ID: 650…204. This is a bitcoin transaction:

The transaction has a method call, init(..., ...). The method call is stored in the memo field, or op_return, of the transaction. Each time you want to update a jig, you send a new transaction to the bitcoin network calling a method. Only the owner of the jig can update it because only the owner of a bitcoin output can spend it.

Coding in the Console

run is a software development kit, or SDK, that helps you run code on bitcoin. You use it to create jigs and update them. You can peruse the whole library of documentation at your leisure:

For now, the easiest way to try it is to play around with the SDK in your internet browser. We’ll use show screenshots of the Chrome browser in this tutorial, but you could use a different browser if you need to.

With the Chrome browser displaying the Jig Explorer page from earlier, open Developer Tools ▸ Console by pressing Control-Shift-J on Windows or Command-Option-J on macOS. The Developer Tools panel will appear and the blue chevron is where you can type in the Console:

The browser Console is a lot like desktop app Terminal if you’ve ever used that. You type in commands and press Return to submit them. The console is also the place where any errors in code will show up.

Create a new instance of run by typing this code next to the blue chevron:

const run = new Run({ network: 'mock' })

The mock network keeps all the bitcoin transactions local to your machine. So while everything that happens on the mock network is a simulation, you’re still using real, signed bitcoin transactions.

Press Return to execute the line of code:

The Chrome Console displays a new line with the result, or return value, of whatever code you executed. When there is no return value, the Console shows undefined. But don’t worry! That doesn’t mean the code didn’t get saved, it just means that nothing got returned. Your code is stored safely in the Console session.

Pro Tip: You would alternatively press Shift-Return whenever you want to write on a new line in the console for writing code and you’re not ready to execute it yet.

Uploading a jig

Earlier you learned that method calls on the jig are stored in a bitcoin transaction. Well, the definition of a jig is stored in the same way. So the definition transaction is like the seed of a tree and the method calls are the branches that grow out from the original transaction:

Copy and paste this code into the Console to create your first jig:

class Dragon extends Jig {
  set(name) {
    this.name = name

Press Return to submit it.

Now is the moment you’ve been waiting for, you’re about to put code into Bitcoin. Type the following code:

const jig = new Dragon()

Press Return to submit it. And that’s it!

Behind the scenes, several things are happening. You created a new instance of the Dragon class–that much is clear. But run has done the heavy lifting for you. The definition of Dragon has been stored as JSON in the output of a bitcoin transaction.

Both the class definition and the new instance are stored in the same bitcoin transaction on different outputs. run is smart enough to save money by making these into a single transaction, but allowing them to operate independently from then on.

You can refer to any jig or class definition by its bitcoin transaction ID and its output index together. We call that the location.

Type the following code:

console.log('class', Dragon.location)
console.log('jig', jig.location)

Pro Tip: You can execute these lines separately by pressing Return after each one, or you can practice adding multiple lines of code before executing by pressing Shift-Return before typing the second line.

Console will print out the locations of the two:

You can see that the class definition and the instance have the same transaction ID (the long first part—something like, ed3…c67) but are have separate output IDs (the short second part, o1 & o2). If you’re not a programmer all this probably sounds über nerdy. The important takeaway is that both the description of the dragon and the actual live dragon are stored on the Bitcoin blockchain, or as we like to say, the data is on-chain.

Updating a jig

So now you’ve seen how to upload the class definition and create the first instance. The next step is to update the instance or set some properties. The Dragon class has a method called set(name). To call the method is as easy as can be. Just type the following code:


You’re using the instance of the Dragon class–the individual dragon–called jig, and you’re giving it a friendly name. The method call is just another Bitcoin transaction. To find out the current state of a jig, your wallet would replay the history of transactions from the beginning.

run has built-in protection to keep you from publishing a transaction that wouldn’t be accepted.

But, you may want to double check whether you’ve made your call correctly. You can access a property of a jig using dot syntax. Type the following code into the Console:


The console will show you the result:

And what about if you wanted to check that the jig had indeed been updated in a new transaction? Type the following code:


The console shows you the result:

So the transaction ID is different now for location than it was before. If you want to access the original location where the jig was first defined, you can use the property origin. The jig is fully expressed by its origin and all the updates leading up to the current location.

Where to go from here?

Congratulations on writing your first jig.

In this tutorial you used the mockchain to speed up development. As a challenge, try moving over to mainnet. Dive into the Docs to guide you along the way. Over time, you’ll pick up all the tools available in the run SDK. If you are successful, not only will you be able to see your jig on the run Explorer, you’ll also be able to see your bitcoin address and transactions on a standard block explorer like WhatsOnChain.com.

We’re at the beginning of something very big here. You’re on the ground level of a new platform. Now anyone can build interactive objects that run on bitcoin. Jigs might just become your new familiar friends.