Tutorial: Running jigs on Bitcoin Mainnet, Part 1

By completing the intro to jigs in the Mockchain Tutorial, you simulated transactions locally on your computer. In this tutorial, you’ll learn how to send transactions to the real Bitcoin mainnet.

Getting started

As a member of the alpha test group, you received a ZIP file. Extract all the files in the ZIP you received.

Open getting_started.html in the Firefox browser.

Pro tip: We’ve also included run.js on our Docs page, so you can play in the Console while viewing the documentation.

Open the Web Console in Firefox by pressing Control-Shift-K on Windows or Command-Option-K on macOS.

Create a new empty instance of run by typing this code into the command prompt:

const run = new Run()

Press Return to submit the command:

If everything went correctly, you’ll see undefined as the result. That means there was no error and you’re ready to continue. 🙌

Understanding custody

When you create a new empty instance of Run, you are automatically assigned a random private key using the bsv JavaScript Library. The private key is constructed locally and is not shared with any server. If you’ve ever swiped a Money Button, you’re familiar with this experience:

The private key for Money Button resides locally in your browser and explicitly not on the server. The wallet is non-custodial; no one can spend the money except for you.

Noting down your private key

The first thing you’ll want to do is write down your private key since there is no backup.

Exercise caution: No one will be able to help you recover your purse if you skip this step and close your browser.

To get your private key, type the following code:


Press Return to submit it:

Copy the private key into your password manager. If you’re unsure about that, check out a tutorial about how to manage your keys with an app called, Enpass.

Note: Don’t store private keys unencrypted on your computer as notes or text files. Also, don’t share your private key with anyone. If someone gets your private key, they can spend your bitcoin.

Finding your purse address

Your purse address is what you give people who want to send you bitcoin. You’re going to use your purse address to fund your Run instance so that you will be able to upload code and call methods on jigs.

To figure out what address you need to use, type the following code:


Press Return to submit it. Console will display your bitcoin address.

Funding your Run wallet

You can fund this address using Electrum SV or HandCash. Or you can use Money Button with this convenient widget:

Convenient widget 😎

Fund your purse wallet

Copy the address and send some BSV using the wallet of your choice. We recommend just sending $1 so that you can pay for the mining fees when sending your transactions. Once you’ve sent a bit of money to the purse, you’re ready to upload the code for a jig. You can have at least 100 interactions with jigs for $1 USD.

In the future, Run will be integrated into wallets so that users can easily send jigs to each other. Also, companies could use a Pay Server to fund transaction fees, so users won’t need to use their own money at all! 🤩

Understanding the commodity ledger

The code for a jig is stored in a Bitcoin transaction. It is optimized and stored as text in the memo field, known as the op_return. Miners charge transaction fees based on the number of bytes. Right now, the standard is one satoshi per byte. 1sat is the smallest unit of bitcoin, or 0.00000001 BSV.

The longer your code is, the more you’ll have to pay. But, don’t worry, even substantially long jig code might cost only one US cent (1¢):

Bitcoin is a commodity ledger. That means anyone can pay for space to record a transaction. A transaction could send bitcoin at money, but it could also represent other things including posting data or changing the ownership of a non-bitcoin asset like a digital pet or a land title.

It is important for the space in the commodity ledger to be valuable to prevent spam. However, everything that is worth recording for a fraction of a cent can be recorded and backed by the full strength of the network. The ledger is a neutral territory where all people, companies, and governments can collaborate together.

Ownership of jigs like creating, updating, or sending are all the kind of transactions that are important enough to pay the mining fee.

Using a block explorer

Open a new browser tab to WhatsOnChain. To check the amount of bitcoin in your purse address, search for your address:

Here’s what’s happening in that screenshot:

  1. Your address will be different than the one in the screenshot because each person has a unique purse.
  2. Look at the transaction to verify that you’ve got some money in your purse. If you have a transaction for something like 0.005 BSV, then you’re ready to post transactions.
  3. While the transaction has the status of Unconfirmed, the balance in the address will still show “0”. But don’t worry, you can spend unconfirmed money using Run.

Writing code to the blockchain

Navigate to the first tab with the Run page that has the open Console. Create a new jig by typing the following code:

Pro tip: You can create a new line in command prompt without executing code by pressing Shift-Return. Or for speed, you can copy and paste the following code in its entirety.

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

Dragon.icon = { emoji: '🐉' }

Press Return to execute the code.

You defined a Dragon jig with a method to set the animal’s name and an icon. The code is called the class definition or the type of your jig.

Advanced programmers: We keep a best practice to support JavaScript 2015 (ES6) for maximum compatibility with Node.js. In the code above, you set the icon metadata outside of the class because that's how static properties work in ES6.

The definition of the class is like the schematic or blueprint for the jig. Now that you’ve got the blueprint, you can give birth to a real instance.

Create an instance of the class by typing this code:

const dragon = new Dragon()

Now your dragon is living and breathing:

By convention, the instance uses a lowercase first letter like dragon, and the type uses an uppercase first letter like Dragon.

Check the origin of the type:


Then check the origin of the instance:


The origin is composed of two pieces, the transaction ID (before the underscore) and the output index (after the underscore).

Both the type and the instance have the same transaction ID, but a different output index. You can see the difference on a block explorer. Copy the transaction ID—the part before the underscore:

Navigate to the WhatsOnChain tab and search for the transaction ID:

The output indexes start at zero, so they are: o0, o1, o2, o3, etc. In the code you’ve uploaded here, the definition of the Dragon type resides at o1 and the instance of dragon resides at o2.

The text displayed in the op_return at o0 contains all the information necessary to interact with the jig. During the alpha test, the text is encrypted, but it will be visible plaintext code once Run is public.

Updating a jig

The origin is the very first location of a jig. So, the origin is the place in the blockchain where you can find the original definition of a jig. Each time you update a jig, its location will change.

Navigate to the first tab with the Run page that has the open Console. Type this code:


Verify that the current location of the instance is the same as its origin:

Update the jig by setting the name of the dragon with this code in the Console:


Now that your dragon has a name, you can also check how the update affected its location:


Copy the new transaction ID (the part before the underscore). Search for it with the block explorer:

Notice how the op_return text at o0 is much shorter this time. That’s because the only information that is stored is the method call, set(name).

You’re looking at the state of a jig. The state consists of the jig definition and all the updates that have been applied to it. If you have the origin, you can step forward in transactions until you can’t go any farther. Using a block explorer, you can step transactions forwards and backwards. In this case, you’re at the current location and so you could step backwards in transactions until you get to the origin transaction.

In the screenshot above, locate the first input, i0, click transaction ID step backwards to the previous transaction.

Now you’re back at the origin transaction:

You can tell that you’re back at the origin transaction because the op_return data is much longer since it contains the full class definition.

Seeing your jig in the Run Explorer

Navigate back to the first tab with the Console open.

Copy the entire location from your dragon, including its output index:

On the getting_started.html page, locate and click the Explorer link in the top right-hand corner of the page:

Paste your location into the search field:

You see your jig, complete with its latest method call, and emoji metadata. Pretty cool, eh!

Where to go from here?

You learned how to upload code onto the live Bitcoin network and check out transactions with a block explorer.

Developing with Run is accessible to everyone, even beginners. If you can write a few lines of JavaScript, you can unleash interactive objects that run on Bitcoin. Jigs can be something always-changing like a digital pet, or they can represent something as unchanging as a still photograph.

As a challenge, try importing the private key from the beginning of tutorial into Electrum SV. That way, you’ll be able to recover your funds and use the money left over from your transactions. Browse the Docs to figure out how you can specify a private key as a parameter when you create a new Run instance. If you succeed, you’ll be able to fund your purse once and then use the same purse over and over again.

Once you’ve given the challenge some thought, discover the solution in the next tutorial: Mainnet, Part 2 with Electrum SV →