@bitcoin-computer/lib

v0.22.0-beta.0

Published

a month ago

Smart Contracts for Bitcoin

Downloads

0High
0Medium
0Low

clemensley

Bitcoin Litecoin Smart Contracts Javascript

The Bitcoin Computer is a protocol for general purpose smart contracts on Bitcoin and Litecoin. It does not rely on a separate token, a separate blockchain or any trusted intermediaries. It works similar to ordinals, runes, and BRC20: you can build applications where users add metadata to a transaction to encode a smart contract interaction, such as minting a token. The software can parse the metadata back into smart contract data, for example which users owns how many tokens.

Our metadata format consists mostly of Javascript expressions to define the state updates. This makes it possible to build not just tokens but all applications directly on Bitcoin.

Use in a Browser

Create a file index.html and open it in your browser.

<html>
  <head>
    <script type="module">
      // Import the library
      import { Computer, Contract } from "https://unpkg.com/@bitcoin-computer/lib/dist/bc-lib.browser.min.mjs"

      // Create a counter smart contract
      class Counter extends Contract {
        constructor() {
          super({ n: 0 })
        }

        inc() {
          this.n += 1
        }
      }

      // Create a wallet and fund it
      const computer = new Computer()
      await computer.faucet(1e5)

      // Mint a new on-chain object
      const counter = await computer.new(Counter)
      document.getElementById("count").innerHTML = counter.n

      // Update the on-chain object
      await counter.inc()
      document.getElementById("count").innerHTML = counter.n
    </script>
  </head>

  <body>
    Count: <span id='count'>*</span>
  </body>
</html>

You should see Count: * at first, then Count: 0 and then Count: 1.

Use with Node.js

You need to have node.js installed. First install the Bitcoin Computer library.

npm install @bitcoin-computer/lib

Then create a file index.mjs containing a script that defines a Counter smart contract, mints a Counter object and the updates it.

import { Computer, Contract } from '@bitcoin-computer/lib'

// A smart contract
class Counter extends Contract {
  constructor() {
    super({ n: 0 })
  }

  inc() {
    this.n += 1
  }
}

// Create and fund a Bitcoin Computer wallet
const computer = new Computer()
await computer.faucet(1e5)

// Deploy a smart contract and create an object
const counter = await computer.new(Counter)

// Update the object
await counter.inc()

// Log the object
console.log(counter)

Execute the script.

node index.mjs

The expected output is:

Counter {
  n: 1,
  _id: '656...024:0',
  _rev: '90f...73f:0',
  _root: '656...024:0',
  _amount: 7860,
  _owners: ['037...954']
}

Run Your Own Node

By default, an instance of the Computer class will connect to a Bitcoin Computer Node on regtest LTC at https://rltc.node.bitcoincomputer.io. You can run your own Bitcoin Computer node, see here for instructions.

To connect to your node, set the url parameter as shown below (see here for more configuration options). Make sure that the parameters chain and network match your node's configuration.

// Connect Bitcoin Computer wallet to a Bitcoin Computer node url
const computer = new Computer({ 
  url: 'http://localhost:1031',
  chain: 'LTC',
  network: 'regtest'
})

Api

Constructor

Creates a new client side wallet. You can pass a mnemonic as well a chain and network to the constructor as well as other optional parameters.

const computer = new Computer({
  chain: 'LTC'
  network: 'mainnet',
  mnemonic: 'replace this seed'
  addressType: 'p2wpkh',
  path: "m/44'/0'/0'/0",
  url: 'https://my-ltc-node.com',
  satPerByte: 1
})

New

Creates a smart object from a class and arguments to the constructor. An output of a Bitcoin transaction, that is inscribed with the constructor call, represents the smart object. The transaction id and output number is the id of the smart object.

A smart object can be updated through function calls. Function calls are also recorded in transactions. The new state of the object is represented by an output of this transaction that is inscribed with the function call. This output is the revision of a smart object.

class A extends Contract {
  constructor(n) {
    this.n = n
  }
}
const a = await computer.new(A, [1])
expect(a).to.deep.equal({
  n: 1,
  _id: '667c...2357:0',
  _rev: '667c...2357:0',
  _root: '667c...2357:0',
  _owners: [computer.getPublicKey()],
  _amount: 5820
})

Sync

Compute the value of a smart object given its revision.

const synced = await computer.sync(a._rev)
expect(synced).to.deep.equal(a)

Deploy

Deploys an ES6 module to Bitcoin. The module is inscribed in a Bitcoin transaction and the transaction id is the module specifier.

const revA = await computer.deploy(
  `export class A {}`
)

const revB = await computer.deploy(`
  import { A } from '${revA}'
  export class B extends A {}
`)

Load

Loads an ES6 module from the blockchain given a modules specifier.

class A {}
const rev = await computer.deploy(`export ${A}`)
const { A: Loaded } = await computer.load(rev)
expect(Loaded).to.equal(A)

Encode

Inputs a Javascript expression, possibly a module specifier, and possibly a "blockchain environment" that maps the (free) variables of the expression to utxos. The expression is evaluated in the scope of the module, substituting the (free) variables for the values computed for the respective utxo. A transaction is broadcast that spends the utxos, has one output for each object in the new state, and is inscribed with the expression, the module specifier and the blockchain environment. Returns the changed state after the evaluation and a transaction.

const { effect, tx } = await computer.encode({ exp: `${A} new A()` })

Decode

Inputs a revision (transaction id and output number) and returns a Javascript expression, a module specifier, and a blockchain environment, if present.

const decoded = await computer.decode(tx)
expect(decoded).to.deep.equal({ exp: `${A} new A()` })

Query

Finds smart objects by module specifier or by owner. Also finds the latest revision of a smart object.

const revs = await computer.query({ publicKey })
expect(revs).eq(/* all revisions owned by publicKey */)

Faucet

Fund a client side library object on regtest. This is practical for testing.

await computer.faucet(0.001e8)

RPC

Access the RPC interface of the Bitcoin node

await computer.rpcCall('getBlockchainInfo', '')

Wallet Functionality

sign. Signs a Bitcoin transaction
broadcast. Broadcasts a Bitcoin transaction
send. Sends satoshis to an address
getAddress. Returns the Bitcoin address of the computer wallet
getBalance. Returns the balance in satoshi

Documentation

Have a look at the docs.

Getting Help

If you have any questions, please let us know on Telegram, Twitter, or by email [email protected].

Price

The Bitcoin Computer is, and will always be, free on testnet and regtest. This version of the Bitcoin Computer library is also free on mainnet, but we reserve the right to charge a small amount per transaction in future versions. Currently only miner fees apply.

Development Status

We are in beta, so there is a possibility of bugs.

Legal Notice

Sanctioned Users are Prohibited. You may not access or use software developed and published by us if you are (i) a resident of any country with which transactions or dealings are prohibited by governmental sanctions imposed by the U.S., the United Nations, the European Union, the United Kingdom, or any other applicable jurisdiction (collectively, “Sanctions Regimes”); (ii) a person, entity or government prohibited under an applicable Sanctions Regime (“Sanctioned Person”), including the Office of Foreign Assets Control, Specially Designated Nationals and Blocked Persons List; or (iii) prohibited from accessing or using the Software pursuant to the laws, rules, and regulations in the jurisdiction in which you reside or otherwise access and use the Software.

Users Must Comply with Applicable Law. You may only access or use the Software in compliance with laws, rules, and regulations in the jurisdiction in which you reside or otherwise access and use the Software, including, as applicable, Sanctions Regimes, anti-money laundering laws and regulations, and securities laws and regulations.

BCDB Does Not Endorse or Promote User Software Activity. We are publishing certain portions of the Software, on an open-source basis, to demonstrate the utility of the Bitcoin Computer. As this Software is open-source, it may be modified and deployed for a wide range of uses that we may not have intended. We do not endorse or promote, and expressly disclaim liability for, any non-BCDB use or modification of the Software.

License

This software is licensed under the Creative Commons Attribution-NoDerivs 3.0 Unported license.

You are free to: share, copy, and redistribute the material in any medium or format for any purpose, even commercially under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
NoDerivatives — If you remix, transform, or build upon the material, you may not distribute the modified material.

This is a human-readable summary of (and not a substitute for) the license.