Skip to main content

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,
}

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