first

Returns the first revision of a given revision.

Type

  first(rev: string): Promise<string>

Parameters

`rev`

A revision encoded as a string of the form <transaction-id>:<output-number>.

Return Value

Returns the first revision of the same on chain object, that is, its id.

Description

If first is called with a revision for which no output exists, it throws an error Rev not found. If the output exists but contains no object, the same error is thrown. If the output contains an object, first will return the first revision of an object as indicated by the arrows in the figure below.

Example

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

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

    constructor() {
      super({ n: 0 })
    }

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

  let computer: Computer

  before('Create and Fund wallet', async () => {
    computer = new Computer({ chain, network, url })
    await computer.faucet(1e8)
  })

  it('Should work if an object is not updated', async () => {
    const counter = await computer.new(Counter, [])

    // The first of an id is the id
    expect(await computer.first(counter._id)).eq(counter._id)
  })

  it('Should work if an object is updated', async () => {
    const counter = await computer.new(Counter, [])
    await counter.inc()

    // The first is the id even if the object is updated
    expect(await computer.first(counter._id)).eq(counter._id)
    expect(await computer.first(counter._rev)).eq(counter._id)
  })

  it('Should throw an error with a revision that does not exist', async () => {
    const noOutput = '0'.repeat(64) + ':0'

    // Throws because there is no output with that revision
    await expect(computer.first(noOutput)).to.be.rejectedWith(/Rev .* not found/)
  })

  it('Should throw an error with a revision that does not contain an object', async () => {
    const counter = await computer.new(Counter, [])
    const noObject = counter._id.split(':')[0] + ':1'

    // Throws because there is no object at the output with that revision
    await expect(computer.first(noObject)).to.be.rejectedWith(/Rev .* not found/)
  })
})

Source