Advanced Usage

Standard Metadata

Wallets, explorers, and exchanges will want to show your jigs. You can add special metadata to any jig to help these apps and services do so. Metadata is stored as an object called metadata on your jig, code, or berry, which contains various properties. The following common properties are called standard metadata:

Presentation

Property	Type	Description
name	string	String name to use in place of the class or function name
description	string	Short sentence, less than 80 characters, that describes the jig for users
emoji	string	Single UTF-8 emoji character to represent the jig
image	string	Reference to an SVG or PNG image stored using B://
audio	string	Reference to an audio file stored using B://
glbModel	string	Reference to GLB file representing a 3d model stored using B://

Attribution and Licensing

Property	Type	Description
author	string markdown	Name of the creator for the code or content
title	string markdown	Title of the content
source	string markdown	URL where the content was found
license	string markdown	License for the code or content

Media stored on-chain using the B:// protocol may be used as metadata for images, audio, or 3D models. To reference previously-uploaded data, use a string formatted either as "b://<txid>" or "b://<txid>_o<vout>". If vout is present, it must be zero-indexed. If it is not present, the first B output in the transaction is used. To upload B data, you may use the EasyB CLI tool.

You can start by setting these properties on your jig classes, as seen to the right. By convention, jig instances will automatically use the metadata from their class. However, jig instances may also have their own metadata that overrides its class metadata. You can put any information in metadata you deem important, even properties that are not listed above.

Warning: For performance reasons, we recommended that B:// media metadata use a b:// uri string rather than the previously-recommended B berry objects.

class DigitalPet extends Jig { }

DigitalPet.metadata = {
  author: 'Maximus',
  license: 'MIT',
  emoji: '🐉'
}

run.deploy(DigitalPet)

Batch Transactions

Multiple updates may be batched together in a single Bitcoin transaction. Batching makes the actions atomic, meaning all of them happen or none of them happen. This is great when two users want to exchange jigs, for example. If any errors occur while publishing the updates, all of the jig changes in the transaction will be reverted. Besides making updates atomic, batching also reduces fees.

Any number of updates may be batched together from different jigs. Call run.transaction() and pass in a callback function that includes all of the actions that you want batched together. Then call run.sync() to wait for the updates to publish. If you need more advanced transaction control, see the Transaction API

Owners must still sign off on any updates to a jig, so if you just created a jig in a new output, you can't yet call a method on it because its owner can't sign. If you just sent a jig to someone, they also can't use it until the next transaction.

Use two jigs separately in one transaction

run.transaction(() => {

  new SomeJig()

  anotherJig.send(address)

})

await run.sync()

Caller Variable

Within code, there is a special caller variable that is available. This variable is always set to the jig or jig class that called the current method, or null if the current method was invoked from application code. Sidekicks are transparent and will never be a caller.

You can use caller to store a jig's creator, enforce that a jig may only be created by a specific parent, or create administrator jigs that uniquely can call special methods.

Storing the parent jig

class Child extends Jig {

  init() {

    this.parent = caller

  }

}

Enforcing a method may only be called by certain classes

class Database extends Jig {

  init(rootUser) {

    this.rootUser = rootUser

  }

  deleteAll() {

    if (caller !== this.rootUser) throw new Error('only the root user may delete the database')

  }

}

class User extends Jig {

  deleteDatabase(database) {

    database.deleteAll()

  }

}

Limiting Interactivity

By default, any jig may interact with any other jig in a transaction. Jigs may be atomically swapped, stored on each other, created from each other, and more. However, the downside is that when jigs interact with other jigs, all of the code for those other jigs needs to be trusted by anyone who wishes to load those jigs later. Run maintains a global trust list, but apps and token issuers may want to avoid the risk that there jigs may be un-loadable by restricting their code and jig instances so that they can only interact with certain other jigs. This removes the risk that a jig might not be redeemable by a service after it interacts with other code that the service doesn't yet trust.

To limit interactivity, you can set the interactive property on your class or function to false. When code is non-interactive, it can only interact with itself, its instances, and any references it has to other code. Run enforces this.

Create a token that can only interact with itself

class MoneyBucks extends Token { }

MoneyBucks.interactive = false

run.deploy(MoneyBucks)

Friends

To customize interactivity on classes with interactive = false, a convention to allow which Code your jigs can interact with is setting a friends array on the class definition.

Additionally, you may want to customize friends in the future, so implementing a static method to set friends after the initial deployment is a good idea.

class MoneyCoin extends Token {

  static setFriends(friends) {

    this.friends = friends;

  }

}

MoneyCoin.friends = [friendsClass];

Private Properties

Jigs may have private methods and private properties.

Private methods are useful when you have internal helper methods that shouldn't be called from outside. To make a method private, you put an underscore before the method name. When a method is private, it can only be called by the current jig, a jig of the same class, or the jig class itself. If a different jig attempts to call a private method, Run will throw an error.

Run supports private properties too. Like methods, you put an underscore before the property name to make it private. You can use private properties to hide state that shouldn't be used by other jigs. Private properties may only be read from inside the current jig, from a jig of the same class, or from the class itself. If you try to access a private property from another class, Run will throw an error.

 Warning: Private properties are not encrypted. They are a tool to control the surface API, not a tool for secrecy.

class TradingCard extends Jig {

  send(to) {

    this._checkNotBlacklisted(to)

    this.owner = to

  }

  _checkNotBlacklisted(owner) {

    if (TradingCard.blacklist.includes(owner)) {

      throw new Error('blacklisted')

    }

  }

}

TradingCard.blacklist = [cheaterAddress]

Auth Method

Every jig and every code has an auth() method on it. To auth means to spend a jig, forcing its owner to approve of any actions performed. Auth also ensures that the jig's state is the latest. You may use auth() for many purposes, such as to have a class approve of the creation of instances, as seen to the right. You may also use it to get approval from several jigs before performing some action. For example, you may require that several players in a game auth using their characters for some shared action to take place, like moving on to the next round. Authing is a fundamental action that will become more useful to you over time.

Limit the creation of jig instances by forcing the class to auth

class SingleTonMonster extends Jig {

  init() {

    SingleTonMonster.auth()

  }

}

Code Presets

When you wish to create an instance of a jig from a class you've already deployed, you have two options. Either you can load the class from the blockchain via run.load() and then create an instance, or you can create an instance from a local class that has presets applied. When a local class has presets, Run doesn't have to download the code from the blockchain. Presets are a great way to share jig classes in NPM libraries.

You can use presets by uploading your code to each Bitcoin network you wish to support using run.deploy() in a script. The presets are origin, location, nonce, owner, and satoshis set onto a presets object for the given network. Run will detect these presets and automatically use the origins and locations on the appropriate network.

class Dragon extends Jig {

  set(name) {

    this.name = name

  }

}

Dragon.presets = {

  main: {

    origin: 'bee45c75c37a289517f33ebfa051601c9610ccc56fbddfbabc44413db5b0bc1b_o1',

    location: 'bee45c75c37a289517f33ebfa051601c9610ccc56fbddfbabc44413db5b0bc1b_o1',

    nonce: 1,

    owner: '13amCautaFqwbWV6MoC86xrh96W4fXGfDV',

    satoshis: 0

  }

}

Berries

Third-party protocols, like Twetch, B, and Metanet, may be used in Run as berries. Berries are JavaScript objects that deterministically capture data on the blockchain that is outside Run. If you can write code to parse an OP_RETURN, you can create Berries. Berries are more than data though. They are typed objects with methods, and they may be passed into jigs, stored as properties, cached, and more.

To load berries using an existing Berry class, you call BerryClass.load() and pass in the path to load, which is often a transaction ID. Run ships with one berry class, B, that may be used to load B:// protocol data.

To define a new Berry protocol, you create a class that extends from the base Berry class and implement the static pluck() method and init() method. Run calls your pluck() method to load data for that path into a JavaScript object. The second parameter to pluck is a method that allows you to fetch transactions from the blockchain. Run fetches transaction data in raw hex format, but you can parse it using the txo or Tx helpers. In pluck(), you instantiate a berry, which will call your init() method.

Once loaded, berries have locations just like jigs. Berry locations are slightly more advanced though and include the class location, the path, and more, in the form: <berry_class_location>?berry=<path>&hash=<state-hash>&version=<protocol>. This is a unique identifier that allows them to be safely referenced and cached.

 Note: If this seems complex, don't worry! We expect most users will not have to write their own berry classes. Like plugins, there will be many berry protocols to choose from in the future. Stay tuned.

Load a metanet node

const txid = '2f24d7edb8de0ef534d8e0bc2413eddda451b4accc481519a1647d7af79d8e88'

const node = await MetanetNode.load(txid)

Define the MetanetNode Berry

class MetanetNode extends Berry {

  // Its constructor can only be called by its pluck function. Run guarantees this.

  init(pnode, parent, data) {

    this.pnode = pnode

    this.parent = parent

    this.data = data

  }

  // Run calls this pluck function when you call run.load with a Berry class.

  static async pluck(location, fetch) {

    const data = txo(await fetch(location))

    if (data.out[0].s1 === 'meta') {

      const pnode = data.out[0].s2

      const txidParent = data.out[0].s3

      const data = data.out[0].s4

      if (data === 'METANET_ROOT') {

        return new MetanetNode(pnode, null, data)

      } else {

        const parentNode = await MetanetNode.load(txidParent)

        return new MetanetNode(pnode, parentNode, data)

      }

    }

  }

}

MetanetNode.deps = { txo: Run.extra.txo }

Locks

The default owner for a jig is a Bitcoin address. This is a great default, but sometimes you'll want more advanced ownership. For example, you may want a group to own a jig, so that no one party has exclusive control. Or you may wish for a jig to be provably owned by nobody. Both of these and more are possible with locks.

A lock is an object that produces a Bitcoin output script. You can set one as the owner on your jigs. Run ships with a Group lock class for multi-sig ownership, and you may also create your own locks by implementing the Lock API. Your lock class will have two methods: script() and domain(). script() returns the bitcoin output script in hex format, and should be safe to call with any state. domain() returns the maximum size of the unlocking script for this lock. After implementing these methods, you set the owner of a jig to an instance of your lock, and Run will build its transaction output.

You'll probably also want to unlock your jigs to update them. To do that, create a corresponding key by implementing the Owner API. Your implementation of the Owner API requires two methods: sign() and nextOwner().

Locks are deterministic, typed, and run in a sandbox environment. This means they can be safely used inside jigs. But this also means they can't use the bsv library or similar external code. Run provides an asm helper function to fill the gap when building custom scripts inside Lock classes.

 Note: If this seems complex, don't worry! There will be many types of lock classes to choose from in the future, and most users won't need to write their own. Stay tuned.

Send a token to a P2PK output script

class PubkeyLock {

  constructor(pubkey) { this.pubkey = pubkey }

  script() { return asm(`${this.pubkey} OP_CHECKSIG`) }

  domain() { return 74 }

}

PubkeyLock.deps = { asm }

token.send(new PubkeyLock(pubkey))

A provably unspendable lock

class Unspendable {

  script() { return asm('OP_RETURN') }

  domain() { return 0 }

}

Unspendable.deps = { asm }

Where to go from here

Now, you can head over to Tips and Tricks