Signature Templates

When a contract function has a sig parameter, it needs a cryptographic signature from a private key for the spending transaction. In place of a signature, a SignatureTemplate can be passed, which will generate the correct signature when the transaction is built.

tip

SignatureTemplate can be used with a Contract as function argument to generate a signature automatically, or can be used in the TransactionBuilder to create an Unlocker for a P2PKH UTXO.

SignatureTemplate

Constructor

new SignatureTemplate(
  signer: Keypair | Uint8Array | string,
  sighashType?: SighashType,
  signatureAlgorithm?: SignatureAlgorithm
)

In place of a signature, a SignatureTemplate can be passed, which will generate the correct signature using the signer parameter. This signer can be any representation of a private key, including WIF strings, BCHJS' ECPair, bitcore-lib-cash' PrivateKey, or binary private keys represented as Uint8Array. This ensures that SignatureTemplate can be used with any BCH library.

Example

const aliceWif = 'L4vmKsStbQaCvaKPnCzdRArZgdAxTqVx8vjMGLW5nHtWdRguiRi1';
const aliceSignatureTemplate = new SignatureTemplate(aliceWif)

const transferDetails = await new TransactionBuilder({ provider })
  .addInput(selectedContractUtxo, contract.unlock.transfer(aliceSignatureTemplate))
  .addOutput({
    to: 'bitcoincash:qrhea03074073ff3zv9whh0nggxc7k03ssh8jv9mkx',
    amount: 10000n
  })
  .send();

The sighashType and signatureAlgorithm options are covered under 'Advanced Usage'.

SignatureTemplate Properties

privateKey

The SignatureTemplate exposes the private key it signs with as a property. Whichever format the signer was passed in (WIF, hex string, Uint8Array or a Keypair object), it is decoded to raw private key bytes.

signatureTemplate.privateKey: Uint8Array

publicKey

The SignatureTemplate exposes the matching public key as a property:

signatureTemplate.publicKey: Uint8Array

sighashType

The configured sighash type is exposed as a property. Note that the BCH fork ID flag is always applied on top of this value when signing, since it is required by BCH consensus. Its possible values are covered under 'Advanced Usage'.

signatureAlgorithm

The configured signature algorithm is exposed as a property. Its possible values are covered under 'Advanced Usage'.

signatureTemplate.signatureAlgorithm: SignatureAlgorithm

SignatureTemplate Methods

unlockP2PKH()

Importantly the SignatureTemplate can also be used to generate the Unlocker for a P2PKH UTXO in the following way:

signatureTemplate.unlockP2PKH(): Unlocker

Example

import { aliceTemplate, aliceAddress, transactionBuilder } from './somewhere.js';

const aliceUtxos = await provider.getUtxos(aliceAddress);
transactionBuilder.addInput(aliceUtxos[0], aliceTemplate.unlockP2PKH());

signMessageHash()

The SignatureTemplate also has a helper method to sign a message hash, which can be used to sign non-transaction messages. This is useful for generating datasig signatures for smart contract use cases.

signatureTemplate.signMessageHash(message: Uint8Array): Uint8Array

Example

import { aliceTemplate } from './somewhere.js';
import { sha256 } from '@cashscript/utils';
import { hexToBin } from '@bitauth/libauth';

const signature = aliceTemplate.signMessageHash(sha256(hexToBin('0000000000000000000000')));

Advanced Usage

SighashType

The default sighashType is SighashType.SIGHASH_ALL | SighashType.SIGHASH_UTXOS because this is the most secure option for smart contract use cases.

export enum SighashType {
  SIGHASH_ALL = 0x01,
  SIGHASH_NONE = 0x02,
  SIGHASH_SINGLE = 0x03,
  SIGHASH_UTXOS = 0x20,
  SIGHASH_ANYONECANPAY = 0x80,
}

SIGHASH_ALL, SIGHASH_NONE and SIGHASH_SINGLE choose which outputs are signed, while SIGHASH_UTXOS and SIGHASH_ANYONECANPAY are modifiers that can be OR'd on top to change what else is committed to. For a full technical breakdown of the signing serialization and every valid flag combination, see the Bitcoin Cash transaction signing reference.

Flag	Value	Commits to	Typical use
SIGHASH_ALL	0x01	all inputs and all outputs	sign the exact transaction
SIGHASH_NONE	0x02	all inputs, but no outputs	let the outputs be decided after signing
SIGHASH_SINGLE	0x03	all inputs, and only the one output at the same index as the signed input	pair a single input to a single output
SIGHASH_UTXOS	0x20	(modifier) additionally commits to the full contents of the UTXOs being spent	recommended for all contracts — see below
SIGHASH_ANYONECANPAY	0x80	(modifier) only the current input, allowing other inputs to be added	crowdfunding-style transactions where anyone can add an input

Example

const wif = 'L4vmKsStbQaCvaKPnCzdRArZgdAxTqVx8vjMGLW5nHtWdRguiRi1';

const signatureTemplate = new SignatureTemplate(
  wif, SighashType.SIGHASH_ALL | SighashType.SIGHASH_UTXOS
);

const configuredSighashType = signatureTemplate.sighashType

SignatureAlgorithm

The signatureAlgorithm parameter determines the cryptographic algorithm used for signing. By default, the modern and compact Schnorr algorithm is used.

export enum SignatureAlgorithm {
  ECDSA = 0x00,
  SCHNORR = 0x01,
}

Example

const wif = 'L4vmKsStbQaCvaKPnCzdRArZgdAxTqVx8vjMGLW5nHtWdRguiRi1';

const sighashType = SighashType.SIGHASH_ALL | SighashType.SIGHASH_UTXOS
const signatureAlgorithm = SignatureAlgorithm.SCHNORR
const signatureTemplate = new SignatureTemplate(wif, sighashType,signatureAlgorithm);

const configuredSignatureAlgorithm = signatureTemplate.signatureAlgorithm