Installing and upgrading TxForge

Using with Node.js

Install TxForge with npm or yarn:

npm install txforge
# or
yarn add txforge

TxForge ships with builds for both ESM and CommonJS. Both import and require() export the same API.

import {
  createForge,    // function
  forgeTx,        // function
  Forge,          // class
  toUTXO,         // function
  getUTXO,        // function
  UTXO,           // class
  Cast,           // class
  isCast,         // function
  Tape,           // class
  toScript,       // function
  casts,          // namespace
  helpers,        // namespace
  macros,         // namespace
  deps            // namespace
} from 'txforge'

Using on the Web

If you are developing using a front-end build tool like EsBuild or Webpack, then you can add TxForge to your project with npm or yarn as above.

Alternatively you can use in a browser via a CDN. Optionally you can use the bundled build which includes nimble in the package (accessed on the deps namespace).

<script src="https://unpkg.com/@runonbitcoin/nimble"></script>
<script src="https://unpkg.com/txforge/dist/txforge.min.js"></script>

<!-- or use the bundled version which includes nimble -->
<script src="https://unpkg.com/txforge/dist/txforge.bundled.min.js"></script>

Either way, txforge is added to the global window object, providing access to the same functions and classes as specified above.

const { forgeTx } = txforge
const { P2PKH } = txforge.casts

const tx = forgeTx({
  inputs: [...],
  outputs: [
    P2PKH.lock(100000, { address: user.address })
  ]
})

TxForge 2 upgrade notes

If you've used previous versions of TxForge, conceptually everything is the same. However, v2.0 is a rewrite from top to bottom, powered by a new Bitcoin library, and incorporates some API changes, most notably with how Casts are defined and used.

Here is a summary of the main changes:

» Depends on nimble instead of the bsv JavaScript library

If your project depends heavily on Money Button's bsv library, it may be advisable to stick with the legacy version of TxForge - at lease until you have a clear upgrade plan.

As nimble is lightweight, you can use it alongside bsv if necessary. However, the reason we have switched to nimble is we question whether the Money Button library is being well maintained. Long term, aiming to migrate to nimble may be a safer bet for your project.

» Simpler functions for composing transactions

TxForge 2 introduces forgeTx() and createForge() functions which are preferred over manually instantiating and working with Forge instances.

» Inputs and outputs must be Cast instances

Previously outputs could be defined using bare objects. For example an object with an address property would automatically be turned into a P2PKH Cast. This is no longer the case - every input and output must be a Cast instance.

» Redesigned Cast API

Custom Casts created for legacy TxForge will not work in version 2. You will need to refactor them using the all new and powerful Cast and Tape APIs.