pushdrop

A package for creating and redeeming Bitcoin tokens with arbitrary signed payloads stored on the stack

The code is hosted on GitHub and the package is available through NPM.

Installation

npm i pushdrop

Example Usage

const pushdrop = require('pushdrop')

const token_payload = [
  Buffer.from(...),
  Buffer.from(...),
  Buffer.from(...),
  ...
]

const pushdrop_script = await pushdrop.create({
  fields: token_payload,
  key: bsv.PrivateKey.fromHex(key)
})

const unlocking_script = await pushdrop.redeem({
  prevTxId: txid,
  outputIndex: 0,
  outputAmount: amount,
  key: bsv.PrivateKey.fromHex(key),
  lockingScript: script.toHex()
})

API

Table of Contents

• create
  • Parameters
• redeem
  • Parameters
• decode
  • Parameters

create

Creates a script that pays to a public key and includes "PUSH DROP" data signed with the corresponding private key

Parameters

• obj Object All parameters are given in an object (optional, default {})

  • obj.fields Array<(Buffer | string)> The token payload fields to push and drop. Each field is given as a Buffer, or a utf8 string.
  • obj.key (string | PrivateKey) The private key that will sign the token payload. Given in WIF or an instance of bsv PrivateKey. If no key is provided, the BabbageSDK will be used as a signing strategy.
  • obj.ownerKey (string | PublicKey)? The owner's public key, whose private key can unlock the token using the redeem function. If not provided, the signing key will be used. Given in DER (33- or 65-byte hex), or an instance of bsv1 PublicKey. If no signing private key is provided, the BabbageSDK will be used to derive the ownerKey.
  • obj.protocolID string Specify an identifier for the protocol under which this operation is being performed.
  • obj.keyID string An identifier for the message being signed. During verification, or when retrieving the public key used, the same message ID will be required. This can be used to prevent key re-use, even when the same user is using the same protocol to sign multiple messages.
  • obj.counterparty string If specified, the user with this identity key will also be able to verify the signature, as long as they specify the current user's identity key as their counterparty. Must be a hexadecimal string representing a 33-byte or 65-byte value, "self" or "anyone". (optional, default self)
  • obj.ownedByCreator Boolean DEPRECATED - use counterpartyCanVerifyMyOwnership. Retained for backward-compatibility (optional, default false)
  • obj.counterpartyCanVerifyMyOwnership Boolean Indicates whether the token is owned by its creator, assuming protocolID and keyID are being used. (optional, default false)
  • obj.privileged string This indicates whether the privileged keyring should be used for signing, as opposed to the primary keyring. (optional, default false)
  • obj.description string? Describe the high-level operation being performed, so that the user can make an informed decision if permission is needed.
  • obj.disableSignature Boolean? If provided, no signature will be applied to the PushDrop token payload.
  • obj.lockBefore Boolean If set to false, the lock will be after the push and drop parts of the script. (optional, default true)
  • obj.customLock String? If provided, the lock portion of the script will be set to this custom value, and the normal P2PK lock will not be used.

Returns Promise<string> A Bitcoin script hex string containing a P2PK lock and the PUSH DROP data, with a signature over the fields

redeem

Redeems a PushDrop transaction output

Parameters

• obj Object All parameters are given in an object

  • obj.prevTxId string The ID of the transaction to redeem

  • obj.outputIndex Number The index of the transaction output to redeem

  • obj.lockingScript (string | bsv.Script) The locking script of the output to redeem. Given as a hex string or an instance of bsv1 Script.

  • obj.outputAmount Number Number of satoshis in the PushDrop UTXO

  • obj.key (string | bsv.PrivateKey) Private key that can unlock the PushDrop UTXO's P2PK lock. Given as a WIF string or an instance of bsv1 PrivateKey.

  • obj.protocolID string Specify an identifier for the protocol under which this operation is being performed.

  • obj.keyID string An identifier for the message being signed. During verification, or when retrieving the public key used, the same message ID will be required. This can be used to prevent key re-use, even when the same user is using the same protocol to sign multiple messages.

  • obj.description string? Describe the high-level operation being performed, so that the user can make an informed decision if permission is needed.

  • obj.counterparty string If specified, the user with this identity key will also be able to verify the signature, as long as they specify the current user's identity key as their counterparty. Must be a hexadecimal string representing a 33-byte or 65-byte value, "self" or "anyone". (optional, default self)

  • obj.privileged string This indicates whether the privileged keyring should be used for signing, as opposed to the primary keyring. (optional, default false)

  • obj.signSingleOutput Object? If provided, uses SIGHASH_SINGLE instead of SIGHASH_NONE. The input index must be the same as the output index of this output in the transaction.

    • obj.signSingleOutput.satoshis Number? Number of satoshis in the single output to sign
    • obj.signSingleOutput.script (string | bsv.Script)? Output script of the single output to sign (this COULD be another PushDrop script created with the create function, allowing you to continue/spend/update the token). Given as a hex string or an instance of bsv1 Script.

  • obj.inputIndex Number The input in the spending transaction that will unlock the PushDrop UTXO (optional, default 0)

Returns Promise<string> Unlocking script that spends the PushDrop UTXO

decode

Given a PushDrop locking script, returns the fields and lockingKey that were used to create it.

If an invalid (non-PushDrop) script is provided, the return value is undefined. Only valid PushDrop scripts will be properly decoded.

Parameters

• obj Object All parameters are given in an object

  • obj.script String The PushDrop locking script to decode
  • obj.fieldFormat String The format of the fields, either "hex", "base64", "utf8" or "buffer" (optional, default hex)

Returns Object The decoded object, containing fields, signature and lockingPublicKey

License

The license for the code in this repository is the Open BSV License.