banner

Run for JS devs - Part II

Previously, on Run for JS devs

In the first part of this series we were discussing a couple of implications that came with designing software with Jigs.

Today, we’re going to do the same, but it’s mostly related to our development and deployment cycle.

So, let’s talk about…

Jig Versioning

Fact #1: Jigs is code stored in the blockchain

Fact #2: Data in the blockchain is immutable

So let’s say we are working in our code, we finish our first iteration, we test it, it works, we’re happy with it, so we deploy all of our jigs to the blockchain:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class SampleJig extends Run.Jig {
    ...    
    m1() {
        console.log('initial behavior')
    }
}

// and then I deploy the class
run.deploy(SampleJig)
await run.sync()


// and then I create an instance
const sampleInstance = new SampleJig()

// if I do
sampleInstance.m1(); // I'll get "initial behavior" logged in the console, right?

And then, suppose that we keep working on a second iteration, and end up having this:

1
2
3
4
5
6
7
8
9
10
class SampleJig extends Run.Jig {
    init(counter) {
        this.counter = 0
    }
    ...
    m1() {
        this.counter = this.counter + 1
        console.log(`Modified behavior. Counter: ${this.counter}`) 
    } 
}

Implications

While deploying

If you just go and re-deploy your class you are going to create a totally new on-chain class (due to fact #2: data is immutable in the blockchain). This new on-chain class has no relation at all with the original one. The instances of the old class are not going to ever change their behavior to the new one nor going to be part of the same prototype chain. When coding jigs, we must understand we’re dealing with living objects that must be explicitly migrated.

Instead, we need to make an Upgrade. See this documentation entry to understand the technical details of upgrading classes. The gist is that you need to define a script to add your new behavior and state to your jigs.

While developing

Upgrading jigs have also implications in your code. Let’s see a few:

  • State: In the previous example, we added a new instance variable called counter. Instances of the first version of the class do not have that set. So, depending on the instance that you are executing the code in, it’ll work or won’t. If you happen to add state, you need to check if it’s there, and if not, explicitly initialize it
  • Ownership: You can only upgrade jigs that you own. In order for you to upgrade other’s people jigs, you’ll need them to authorize the process. That might be solved by providing a method for the users to log in and authorize the upgrade, or designing your application in such a way that upgradable jigs always belong to you, if that’s possible
  • Code presence: This might sound obvious, but when doing upgrades, you’re doing a full replacement of your code. Running OldJigClass.upgrade(NewJigClass) will replace everything in the old class to the methods and variables defined in the new one. So you have to carefully define a migration script that adds the new or modified behavior, and removes the code that needs to be explicitly removed. Again, Upgrading Code section in Run documentation offers a snippet you could use to safely do that. We also have a new tool that’s going to help with this called Runbot that is going to be announced really really soon, so stay tuned!

Wrapping up

As we’ve been doing in this series of Run for Js devs, we are pointing out some details that might change the way you think about designing your abstractions or your development cycle in your JS projects. In this post we analyzed how jigs are different from traditional classes regarding their versioning and how it affects them.

And that’s it!

Stay tuned for more tips!