new

Creates an on-chain object.

Type

;<T extends new (...args: any) => any>(
  constructor: T,
  args?: ConstructorParameters<T>,
  mod?: string,
) =>
  Promise<
    InstanceType<T> & {
      _id: string
      _rev: string
      _root: string
      _satoshis: bigint
      _owners: string[]
      _readers?: string[]
      _url?: string
    }
  >

Parameters

constructor

A named JavaScript class T.

args

Arguments to the constructor of the class T.

mod

Optionally, a string of the form <transaction-id>:<output-number> that references a module.

When a mod is supplied, the module specifier is attached to the top-level created object and automatically propagated to every descendant object created during the constructor execution. This guarantees that the entire object graph produced by a single new call shares the same module membership. The same propagation rule applies during method calls: if the target object (or any argument) carries a mod, every new object created inside the method inherits that module specifier. This behavior enables consistent module-based querying and powerful patterns such as DAOs.

Return Value

If T or one of its sub-objects does not extend from Contract an error is thrown. Otherwise it returns an on-chain object of class T. The object has all the properties specified in T and in addition the properties _id, _rev, _root, _owners, and _satoshis. If the constructor defined properties _url or _readers they must have the types as indicated above.

Description

The new function can create on-chain objects. The creation of a smart object is recorded in a transaction on the blockchain (see here for more details on how it works). Once an on-chain object is created its properties can only be updated through function calls. Every time a function is called, a transaction is broadcast that records the function call on the blockchain. For this reason it is necessary to await on all function calls on an on-chain object. Multiple users can sync to the same smart object to get consensus over its state.

Example

import { Computer, Contract } from '@bitcoin-computer/lib'
import { chain, network, url, expect } from '../../utils/index.js'

describe('new', () => {
  // A smart contract
  class Counter extends Contract {
    n: number

    constructor() {
      super({ n: 0 })
    }
    inc() {
      this.n += 1
    }
  }

  it('Should create a new on-chain object', async () => {
    // Create and fund wallet
    const computer = new Computer({ chain, network, url })
    await computer.faucet(1e8)

    // Create an on-chain object
    const counter = await computer.new(Counter, [])
    expect(counter).to.matchPattern({
      n: 0,
      _id: (id: string) => typeof id === 'string',
      _rev: (rev: string) => typeof rev === 'string',
      _root: (root: string) => typeof root === 'string',
      _satoshis: (satoshis: number) => typeof satoshis === 'bigint',
      _owners: [computer.getPublicKey()],
    })

    // Update an on-chain object
    await counter.inc()
    expect(counter).to.matchPattern({
      n: 1,
      _id: (id: string) => typeof id === 'string',
      _rev: (rev: string) => typeof rev === 'string',
      _root: (root: string) => typeof root === 'string',
      _satoshis: (satoshis: number) => typeof satoshis === 'bigint',
      _owners: [computer.getPublicKey()],
    })
  })
})

Source