Difference between revisions of "Installing the run sdk"
| Line 2: | Line 2: | ||
Another solution is to download the SDK as a zip file from [https://run.network/ https://run.network/]. When writing this the latest version is [https://github.com/runonbitcoin/sdk/archive/refs/tags/v0.6.37.zip version 0.6.37]. | Another solution is to download the SDK as a zip file from [https://run.network/ https://run.network/]. When writing this the latest version is [https://github.com/runonbitcoin/sdk/archive/refs/tags/v0.6.37.zip version 0.6.37]. | ||
| + | |||
= Getting Started = | = Getting Started = | ||
| + | |||
(note the following section was originally a simple copy/paster from [https://run.network/docs/#getting-started the official doc]) | (note the following section was originally a simple copy/paster from [https://run.network/docs/#getting-started the official doc]) | ||
| + | |||
== Installation == | == Installation == | ||
| + | |||
<p>If you're new to Run, let the </p>[https://run.network/lessons tutorial series]<p> guide your journey to get acquainted. You can write code without installing anything. The web browser Console will be your playground.</p><p>The details written here in the Docs have example code in the sidebar on the right-hand side. Anything you read in paragraphs, you can preview in-action over there. ⇥</p><p>Run works everywhere including all major browsers, on desktop and mobile, as well as Node.js 10+ on servers. The Run SDK is written in JavaScript ES6 and uses the </p>[https://github.com/moneybutton/bsv bsv library]<p> to build and sign transactions. To get started:</p> | <p>If you're new to Run, let the </p>[https://run.network/lessons tutorial series]<p> guide your journey to get acquainted. You can write code without installing anything. The web browser Console will be your playground.</p><p>The details written here in the Docs have example code in the sidebar on the right-hand side. Anything you read in paragraphs, you can preview in-action over there. ⇥</p><p>Run works everywhere including all major browsers, on desktop and mobile, as well as Node.js 10+ on servers. The Run SDK is written in JavaScript ES6 and uses the </p>[https://github.com/moneybutton/bsv bsv library]<p> to build and sign transactions. To get started:</p> | ||
*For a webpage: Add <code>bsv.browser.min.js</code> and <code>run.browser.min.js</code> to the <code><head></code> tag. | *For a webpage: Add <code>bsv.browser.min.js</code> and <code>run.browser.min.js</code> to the <code><head></code> tag. | ||
*For Node.js: Run <code>npm install run-sdk</code> to install both the run and bsv libraries | *For Node.js: Run <code>npm install run-sdk</code> to install both the run and bsv libraries | ||
<p>And that's it. All your code and jigs will be saved on-chain and Run will use public APIs to interact with the Bitcoin network. You don't need to deploy any servers to use Run. All the logic works client-side.</p> | <p>And that's it. All your code and jigs will be saved on-chain and Run will use public APIs to interact with the Bitcoin network. You don't need to deploy any servers to use Run. All the logic works client-side.</p> | ||
| + | |||
== Setup == | == Setup == | ||
| − | |||
| − | . | + | A <code>Run</code> instance manages your communication with the Bitcoin network. The default network is <code>main</code> (Mainnet), but for development and testing, we recommend <code>mock</code>. Mock is an in-memory simulation blockchain that does not require funds to use. We like to call it the ''mockchain''. For more configuration options, see [https://run.network/docs/#api-reference-run API Reference: Run]. |
| + | |||
== Creating Jigs == | == Creating Jigs == | ||
| + | |||
<p>Let's begin with a basic jig that stores a value in a variable. Create a jig called <code>SimpleStore</code>. By extending from <code>Jig</code>, the instances of your class will automatically sync to the blockchain. Every jig has an <code>owner</code>. Any code may read jigs but only its <code>owner</code> can update it. The <code>owner</code> is typically a Bitcoin address, and the private key is required to update it.</p><p>In addition to <code>owner</code>, every jig has a <code>location</code>. A jig's <code>location</code> is the pairing of a Bitcoin transaction ID and an output index, and it represents a particular state in time of an object or class on Bitcoin. When you check the <code>location</code> property of a jig, you get its current location. If you wish to get the location where the jig was first deployed, that is called its <code>origin</code>. The <code>origin</code> is unique and will not change, however <code>location</code> changes with every update. After a method call, your jig will have a new <code>location</code> pointing to a Bitcoin transaction containing the last method call.</p> | <p>Let's begin with a basic jig that stores a value in a variable. Create a jig called <code>SimpleStore</code>. By extending from <code>Jig</code>, the instances of your class will automatically sync to the blockchain. Every jig has an <code>owner</code>. Any code may read jigs but only its <code>owner</code> can update it. The <code>owner</code> is typically a Bitcoin address, and the private key is required to update it.</p><p>In addition to <code>owner</code>, every jig has a <code>location</code>. A jig's <code>location</code> is the pairing of a Bitcoin transaction ID and an output index, and it represents a particular state in time of an object or class on Bitcoin. When you check the <code>location</code> property of a jig, you get its current location. If you wish to get the location where the jig was first deployed, that is called its <code>origin</code>. The <code>origin</code> is unique and will not change, however <code>location</code> changes with every update. After a method call, your jig will have a new <code>location</code> pointing to a Bitcoin transaction containing the last method call.</p> | ||
| + | |||
== Loading Jigs == | == Loading Jigs == | ||
| + | |||
<p>The simplest way to load your jigs is to call <code>run.inventory.sync()</code> and then access <code>run.inventory.jigs</code>. <code>run.inventory.sync()</code> will find and load all objects owned by <code>run.owner</code> and place them in the <code>jigs</code> array. Once loaded, you may call methods and use them normally. Alternatively, you may wish to load a particular jig or load a jig in a historical state. To do either, pass the <code>location</code> of the jig you wish to load into <code>run.load()</code>.</p><p>If you've loaded a historical location so that your jig is in a previous state, you'll need to first catch up to the latest state before you'll be allowed to make a method call. <code>sync()</code> will handily fast-forward a jig to its latest state on the blockchain ''without'' triggering a Bitcoin transaction. In the example on the sidebar, if <code>specificJig</code> was in a historical state, you would call <code>specificJig.sync()</code> and then call <code>specificJig.set('abc')</code>. When you accidentally try to update a jig without the jig being in its latest state, Run will safely abort before publishing a Bitcoin transaction and inform you with an error. In that case, you'll just need to add the preceding <code>sync()</code> call and execute your code again. The best practice is to write code in such a way that jigs are always up-to-date in their latest state. Run manages the heavy lifting for you.</p><p><code>sync()</code> also acts as a debugging tool since it surfaces any errors your jigs have after you've made changes to them. If you notice your app acting funny, a well-placed preceding <code>specificJig.sync()</code> can help you uncover the error. You may also call <code>sync()</code> on your <code>Run</code> instance, like this: <code>run.sync()</code>. That'll help you search out any errors from your entire app in ''all'' of the jigs you own.</p> | <p>The simplest way to load your jigs is to call <code>run.inventory.sync()</code> and then access <code>run.inventory.jigs</code>. <code>run.inventory.sync()</code> will find and load all objects owned by <code>run.owner</code> and place them in the <code>jigs</code> array. Once loaded, you may call methods and use them normally. Alternatively, you may wish to load a particular jig or load a jig in a historical state. To do either, pass the <code>location</code> of the jig you wish to load into <code>run.load()</code>.</p><p>If you've loaded a historical location so that your jig is in a previous state, you'll need to first catch up to the latest state before you'll be allowed to make a method call. <code>sync()</code> will handily fast-forward a jig to its latest state on the blockchain ''without'' triggering a Bitcoin transaction. In the example on the sidebar, if <code>specificJig</code> was in a historical state, you would call <code>specificJig.sync()</code> and then call <code>specificJig.set('abc')</code>. When you accidentally try to update a jig without the jig being in its latest state, Run will safely abort before publishing a Bitcoin transaction and inform you with an error. In that case, you'll just need to add the preceding <code>sync()</code> call and execute your code again. The best practice is to write code in such a way that jigs are always up-to-date in their latest state. Run manages the heavy lifting for you.</p><p><code>sync()</code> also acts as a debugging tool since it surfaces any errors your jigs have after you've made changes to them. If you notice your app acting funny, a well-placed preceding <code>specificJig.sync()</code> can help you uncover the error. You may also call <code>sync()</code> on your <code>Run</code> instance, like this: <code>run.sync()</code>. That'll help you search out any errors from your entire app in ''all'' of the jigs you own.</p> | ||
| − | |||
Revision as of 00:24, 14 December 2022
The easiest way to get the latest version is to run npm install run-sdk
Another solution is to download the SDK as a zip file from https://run.network/. When writing this the latest version is version 0.6.37.
Getting Started
(note the following section was originally a simple copy/paster from the official doc)
Installation
If you're new to Run, let the
guide your journey to get acquainted. You can write code without installing anything. The web browser Console will be your playground.
The details written here in the Docs have example code in the sidebar on the right-hand side. Anything you read in paragraphs, you can preview in-action over there. ⇥
Run works everywhere including all major browsers, on desktop and mobile, as well as Node.js 10+ on servers. The Run SDK is written in JavaScript ES6 and uses the
to build and sign transactions. To get started:
- For a webpage: Add
bsv.browser.min.jsandrun.browser.min.jsto the<head>tag. - For Node.js: Run
npm install run-sdkto install both the run and bsv libraries
And that's it. All your code and jigs will be saved on-chain and Run will use public APIs to interact with the Bitcoin network. You don't need to deploy any servers to use Run. All the logic works client-side.
Setup
A Run instance manages your communication with the Bitcoin network. The default network is main (Mainnet), but for development and testing, we recommend mock. Mock is an in-memory simulation blockchain that does not require funds to use. We like to call it the mockchain. For more configuration options, see API Reference: Run.
Creating Jigs
Let's begin with a basic jig that stores a value in a variable. Create a jig called SimpleStore. By extending from Jig, the instances of your class will automatically sync to the blockchain. Every jig has an owner. Any code may read jigs but only its owner can update it. The owner is typically a Bitcoin address, and the private key is required to update it.
In addition to owner, every jig has a location. A jig's location is the pairing of a Bitcoin transaction ID and an output index, and it represents a particular state in time of an object or class on Bitcoin. When you check the location property of a jig, you get its current location. If you wish to get the location where the jig was first deployed, that is called its origin. The origin is unique and will not change, however location changes with every update. After a method call, your jig will have a new location pointing to a Bitcoin transaction containing the last method call.
Loading Jigs
The simplest way to load your jigs is to call run.inventory.sync() and then access run.inventory.jigs. run.inventory.sync() will find and load all objects owned by run.owner and place them in the jigs array. Once loaded, you may call methods and use them normally. Alternatively, you may wish to load a particular jig or load a jig in a historical state. To do either, pass the location of the jig you wish to load into run.load().
If you've loaded a historical location so that your jig is in a previous state, you'll need to first catch up to the latest state before you'll be allowed to make a method call. sync() will handily fast-forward a jig to its latest state on the blockchain without triggering a Bitcoin transaction. In the example on the sidebar, if specificJig was in a historical state, you would call specificJig.sync() and then call specificJig.set('abc'). When you accidentally try to update a jig without the jig being in its latest state, Run will safely abort before publishing a Bitcoin transaction and inform you with an error. In that case, you'll just need to add the preceding sync() call and execute your code again. The best practice is to write code in such a way that jigs are always up-to-date in their latest state. Run manages the heavy lifting for you.
sync() also acts as a debugging tool since it surfaces any errors your jigs have after you've made changes to them. If you notice your app acting funny, a well-placed preceding specificJig.sync() can help you uncover the error. You may also call sync() on your Run instance, like this: run.sync(). That'll help you search out any errors from your entire app in all of the jigs you own.
