Skip to content

Latest commit

 

History

History
1029 lines (662 loc) · 23.7 KB

API.md

File metadata and controls

1029 lines (662 loc) · 23.7 KB
Raw

Table of Contents

BScript

A BScript instance represents a parsed raw bscript or parsed bscript asm string.

It is likely that you will not want to call the BScript constructor directly, but instead use the BScript.fromRaw, BScript.fromAsm or BScript.fromAddress static methods to create a new BScript instance.

Parameters

  • tokens Array<Token> The ordered list of parsed tokens for the script

Examples

const BScript = require('bscript-parser')
const {Token} = BScript
const {opcodeForWord} = Bscript.opcodes

const tokens = [
  Token.opcode(opcodeForWord('OP_HASH160'), 0, 1),
  Token.literal(Buffer.from('c664139327b98043febeab6434eba89bb196d1af', 'hex'), 1, 21),
  Token.opcode(opcodeForWord('OP_EQUAL'), 21, 22)
]

const bscript = new BScript(tokens)

tokens

The script's parsed tokens.

Type: Array<Token>

toAsm

Converts a parsed script to an asm text.

Parameters

  • options Options Options for asm stringification (optional, default {})

Examples

const bscript = BScript.fromRaw('a914c664139327b98043febeab6434eba89bb196d1af87', 'hex')
const asm = bscript.toAsm()
assert.equal(asm, 'OP_HASH160 c664139327b98043febeab6434eba89bb196d1af OP_EQUAL')

Returns string A bscript asm string.

toRaw

Converts a parsed script to raw bscript.

Parameters

  • outputEncoding (null | string) The buffer encoding of the returned raw bscript, or null (the default) to have a buffer returned. (optional, default null)

Examples

const bscript = BScript.fromAsm('OP_HASH160 c664139327b98043febeab6434eba89bb196d1af OP_EQUAL')
const raw = bscript.toRaw('hex')
assert.equal(raw, 'a914c664139327b98043febeab6434eba89bb196d1af87')

Returns (string | Buffer) The parsed script in its raw form

toAddress

Convert a BSCript object into an address.

Either the pubKeyHash, scriptHash, or bech32 option is used when the address is generated, depending on the type of address the script converts to. See the Bitcoin Wiki entry for addresses to learn more about these options and what they mean. If the address is intended to be used on the bitcoin mainnet, you should use the default values.

If the script does not represent an address, undefinedis returned.

Parameters

  • options Options Options for address generation (optional, default {})

Examples

const bscript = BScript.fromAsm('OP_HASH160 52973f3519d5d248004767efb874aa2a3b2b37ce OP_EQUAL')
const address = bscript.toAddress()
assert.equal(address, '39DiX6M1KX2MNvtm44eUu18qdgqxnJgTW8')

Returns (string | undefined) The address for the script or undefined if the script does not convert to an address

scriptType

The script type of the script.

Possible values are:

  • p2pk
  • p2pkh
  • p2sh
  • p2wpkh
  • p2wsh

If the script is not a known standard script type, undefined is returned.

Type: (string | undefined)

Examples

const asm = 'OP_DUP OP_HASH160 f54a5851e9372b87810a8e60cdd2e7cfd80b6e31 OP_EQUALVERIFY OP_CHECKSIG'
const bscript = BScript.fromAsm(asm)
assert.equal('p2pkh', bscript.scriptType)

hasAddress

Whether or not the script is convertible to an address.

Type: boolean

Examples

const asm = 'OP_0 769be9e30613eb5a67efe8ae03805079e8fd5d92'
const bscript = BScript.fromAsm(asm)
assert.equal(true, bscript.hasAddress)
const asm = 'OP_RETURN 636861726c6579206c6f766573206865696469'
const bscript = BScript.fromAsm(asm)
assert.equal(false, bscript.hasAddress)

redeemScript

The redeem script of a p2sh scriptSig.

Type: (BScript | undefined)

Examples

const bscript = BScript.fromRaw('160014983c113b3b34d109e72aa6d4246e2430b3240161', 'hex')
const redeem = bscript.redeemScript
assert.equal(redeem.toRaw('hex'), '0014983c113b3b34d109e72aa6d4246e2430b3240161')

rawToAsm

Convert raw bscript into a bscript asm string.

Parameters

  • rawScript (string | Buffer) The raw bscript
  • optionsOrEncoding (string | null | Options) An Options object, or just the encoding option as a string (optional, default {})

Examples

const {rawToAsm} = require('bscript-parser')
const asm = rawToAsm('a914c664139327b98043febeab6434eba89bb196d1af87', 'hex')
assert.equal(asm, 'OP_HASH160 c664139327b98043febeab6434eba89bb196d1af OP_EQUAL')

Returns string The raw bscript converted to an asm string

asmToRaw

Convert a bscript asm string into raw bscript.

Parameters

  • asmScript string The bscript asm string
  • optionsOrEncoding (string | null | Options) An Options object or just the encoding option (optional, default {})

Examples

const {asmToRaw} = require('bscript-parser')
const raw = asmToRaw('OP_HASH160 c664139327b98043febeab6434eba89bb196d1af OP_EQUAL', 'hex')
assert.equal(raw, 'a914c664139327b98043febeab6434eba89bb196d1af87')

Returns (string | Buffer) The asm string converted to raw bscript

formatAsm

Reformat a bscript asm string.

Parameters

  • asmScript string The bscript asm string
  • options Options The options for the reformatted code (optional, default {})

Examples

const {formatAsm} = require('bscript-parser')
const formatted = formatAsm('HASH160  [c664139327b98043febeab6434eba89bb196d1af]\nOP_EQUAL')
assert.equal(asm, 'OP_HASH160 c664139327b98043febeab6434eba89bb196d1af OP_EQUAL')

Returns string The reformatted asm script.

fromRaw

Create a BScript object from a raw script.

Parameters

  • rawScript (string | Buffer) The raw bscript to parse into a BScript object
  • encoding string The buffer encoding of the raw script if it is a string. Defaults to 'hex'. (optional, default 'hex')

Examples

const raw = a914c664139327b98043febeab6434eba89bb196d1af87
const bscript = BScript.fromRaw(raw, 'hex')
assert.equal(raw, bscript.toRaw('hex'))
  • Throws TypeError When rawScript is not a buffer or not a properly encoded string.
  • Throws Error When the script contains an invalid opcode.

Returns BScript The parsed script object.

fromAsm

Create a BScript object from an asm string.

Parameters

  • asmScript string The bscript asm string to parse into a BScript object
  • options Options Options to be passed to the parser (optional, default {})

Examples

const asm = 'OP_HASH160 52973f3519d5d248004767efb874aa2a3b2b37ce OP_EQUAL'
const bscript = BScript.fromAsm(asm)
assert.equal(asm, bscript.toAsm())
  • Throws Error When asmScript is not a valid asm script.

Returns BScript The parsed script object.

fromAddress

Create a BScript object from a standard address.

Depending on the type of address provided, one of the pubKeyHash, scriptHash, or bech32 option is used when the address is parsed. See the Bitcoin Wiki entry for addresses to learn more about these options and what they mean. If the address is one for the bitcoin mainnet, you should use the default values.

Parameters

  • address string The address being parsed into a script object.
  • options Options The options used for parsing the address. (optional, default {})

Examples

[
  '1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs',
  '39DiX6M1KX2MNvtm44eUu18qdgqxnJgTW8',
  'bc1qq28dxlfuvrp8666vlh73tsrspg8n68atkfqxqwfjl',
  'bc1qqsgucp6ev42uvcw9lnhjyhkz2vhyv9ez4pg003dcerw6ds4nw7q25ssrrlcc'
].forEach((address) => {
  bscript = BScript.fromAddress(address)
  assert.equal(address, bscript.toAddress())
})
  • Throws TypeError When address is not a known standard address.

Returns BSCript The parsed script object.

Options

Options shared by several of the functions provided by this module.

Type: Object

Properties

  • encoding string? The buffer encoding of the input or output raw bscript if it is a string. A value of null will output a raw bscript as a Buffer. The default value is 'hex'.
  • literalStyle string? When generating asm, this setting configures the style in which PUSH_DATA values ar output. The following options are allowed:
    normal
    abcdef012345
    brackets
    [abcdef012345]
    prefixed
    0xabcdef012345
    verbose
    PUSHDATA(6)[abcdef012345]
  • opcodeStyle string? When generating asm, this setting configures the style in which opcode terms are output. The following options are allowed:
    normal
    OP_HASH160
    short
    HASH160
  • terms Object? An object mapping terms to opcodes. This allows terms to be overridden and for non-standard terms to be parsed.
  • opcodes Object? An object mapping opcodes to terms. This allows opcodes to be overriden with non-standard terms.
  • pubKeyHash number? The pub key hash prefix for generating / parsing standard p2pkh addresses.
  • scriptHash number? The script hash prefix for generating / parsing standard p2sh addresses.
  • bech32 string? The prefix used for generating / parsing standard bech32 addresses.
  • allowPlaceHolders boolean? When true, an asm script can be compiled with <placeholder> values. The default is false.

Examples

// These are all the default options
const options = {
  encoding: 'hex',
  literalStyle: 'normal',
  opcodeStyle: 'normal',
  terms: {},
  opcodes: {},
  pubKeyHash: 0x00,
  scriptHash: 0x05,
  bech32: 'bc',
  allowPlaceHolders: false
}

opcodes

Examples

const {opcodes} = require('bscript-parser')

opcodeForWord

Get the opcode of an opcode string

Parameters

  • word string The opcode string.

Examples

assert.equal(135, opcodes.opcodeForWord('OP_EQUAL'))
  • Throws any AssertError When the word is not a valid opcode string.

Returns number The opcode for the word

wordForOpcode

Get the opcode string of an opcode

Parameters

Examples

assert.equal('OP_EQUAL', opcodes.wordForOpcode(135))
  • Throws any AssertionError When the opcode is not a valid opcode.

Returns string The opcode string for the opcode

opcodeIsValid

Determines whether an opcode is valid

Parameters

Examples

assert.equal(true, opcodes.opcodeIsValid(135))
assert.equal(false, opcodes.opcodeIsValid(1000))

Returns boolean true if the opcode is valid, false if not.

wordIsValid

Determines whether an opcode string is valid

Parameters

Examples

assert.equal(true, opcodes.wordIsValid('OP_EQUAL'))
assert.equal(false, opcodes.wordIsValid('OP_BAD'))

Returns boolean true if the word is valid, false if not.

descriptionForOpcode

Gets a description for an opcode

Parameters

Examples

const expected = 'Returns 1 if the inputs are exactly equal, 0 otherwise.'
assert.equal(expected, opcodes.descriptionForOpcode(135))
  • Throws any AssertionError When opcode is invalid.

Returns string The description of the opcode

descriptionForWord

Gets a description for an opcode string

Parameters

Examples

const expected = 'Returns 1 if the inputs are exactly equal, 0 otherwise.'
assert.equal(expected, opcodes.descriptionForWord('OP_EQUAL'))
  • Throws any AssertionError When word is invalid.

Returns string The description of the opcode

inputDescriptionForOpcode

Gets a description of the input for an opcode

Parameters

Examples

const expected = 'x1 x2'
assert.equal(expected, opcodes.inputDescriptionForOpcode(135))
  • Throws any AssertionError When opcode is invalid.

Returns string The description of the opcode's input

inputDescriptionForWord

Gets a description of the input for an opcode string

Parameters

Examples

const expected = 'x1 x2'
assert.equal(expected, opcodes.inputDescriptionForWord('OP_EQUAL'))
  • Throws any AssertionError When word is invalid.

Returns string The description of the opcode's input

outputDescriptionForOpcode

Gets a description of the output for an opcode

Parameters

Examples

const expected = 'True / false'
assert.equal(expected, opcodes.outputDescriptionForOpcode(135))
  • Throws any AssertionError When opcode is invalid.

Returns string The description of the opcode's output

outputDescriptionForWord

Gets a description of the output for an opcode string

Parameters

Examples

const expected = 'True / false'
assert.equal(expected, opcodes.outputDescriptionForWord('OP_EQUAL'))
  • Throws any AssertionError When word is invalid.

Returns string The description of the opcode's output

opcodeIsDisabled

Gets whether or not an opcode is disabled in bitcoin-core

Parameters

Examples

assert.equal(false, opcodes.opcodeIsDisabled(135))
assert.equal(true, opcodes.opcodeIsDisabled(134))
  • Throws any AssertionError When opcode is invalid.

Returns boolean true if the opcode is disabled, false if not

wordIsDisabled

Gets whether or not an opcode string is disabled in bitcoin-core

Parameters

Examples

assert.equal(false, opcodes.opcodeIsDisabled('OP_EQUAL'))
assert.equal(true, opcodes.opcodeIsDisabled('OP_XOR'))
  • Throws any AssertionError When word is invalid.

Returns boolean true if the opcode is disabled, false if not

Token

A Token represents a parsed part of a bscript.

There are three types of tokens:

  • A literal (PUSH_DATA data)
  • An opcode
  • A placeholder (for template scripts only)

Parameters

  • type string One of Token.LITERAL, Token.OPCODE, or Token.PLACEHOLDER
  • value (Buffer | number | string) The value of the token. For a literal, this is the raw pushed data as a Buffer (without the push data opcode). For an opcode, this is the opcode as an integer. For a placeholder, it is the placeholder string.
  • startIndex number The position within the asm text or raw script where the token beings. Note: if source of the script is a raw script that is string encoded, the startIndex is the index within the buffer, not the original encoded string.
  • endIndex number The position within the asm text or raw script where the token ends. Note: if source of the script is a raw script that is string encoded, the endIndex is the index within the buffer, not the original encoded string.

Examples

const {Token} = require('bscript-parser')
token = new Token(Token.LITERAL, Buffer.from('abcdef0123', 'hex'), 0, 10)

toAsm

Convert a token into an asm string.

Parameters

  • options Options Options for asm stringification. The literalStyle, and opcodeStyle parameters are relevant to this method. (optional, default {})

Examples

const token = Token.literal(Buffer.from('c664139327b98043febeab6434eba89bb196d1af', 'hex'))
const asm = token.toAsm({literalStyle: 'verbose'})
assert.equal('PUSH_DATA(20)[c664139327b98043febeab6434eba89bb196d1af]', asm)
const token = Token.opcode(0xa9)
const asm = token.toAsm({opcodeStyle: 'short'})
assert.equal('HASH160', asm)

Returns string The token's asm representation.

toScript

Convert a token into its raw script representation.

Examples

const data = Buffer.from('c664139327b98043febeab6434eba89bb196d1af', 'hex')
const expected = Buffer.from('14c664139327b98043febeab6434eba89bb196d1af', 'hex')
const token = Token.literal(data)
const raw = token.toScript()
assert.equal(0, expected.compare(raw))
const token = Token.opcode(0xa9)
const expexted = Buffer.from([0xa9])
const raw = token.toScript()
assert.equal(0, expected.compare(raw))

Returns Buffer The token's raw bscript representation.

toString

Convert to an asm string.

Returns string

literal

A short-hand helper to create a Token.LITERAL token.

Parameters

Returns Token

opcode

A short-hand helper to create a Token.OPCODE token.

Parameters

  • value integer The opcode value. See the parameters for Token.
  • startIndex number See the parameters for Token
  • endIndex number See the parameters for Token

Returns Token

placeholder

A short-hand helper to create a Token.PLACEHOLDER token.

Parameters

Returns Token

LITERAL

Constant for the type property of a literal token.

Type: string

OPCODE

Constant for the type property of an opcode token.

Type: string

PLACEHOLDER

Constant for the type property of a placeholder token.

Type: string