@bitauth/libauth - npm Package Versions

3.0.0

Major Changes

• #127 e5c275f Thanks @bitjson! - Add support for relative BIP32 derivation

  Relative BIP32 Hierarchical Deterministic (HD) derivation is now supported via the deriveHdPathRelative utility, and the Libauth compiler has been updated to explicitly use relative derivation by default for HdKeys. Absolute derivation has also been enhanced to validate the expected depth of provided HD keys.

  If you application relies on relative derivation but uses deriveHdPath, you'll need to switch to using the new deriveHdPathRelative, as absolute derivation will now fail if provided with a non-zero depth HD key.

  Fixes #49.

• #127 e5c275f Thanks @bitjson! - CashAssembly: .signature is now .ecdsa_signature

  All CashAssembly scripts using the .signature operation should instead call .ecdsa_signature or switch to .schnorr_signature.

  Additionally, signing_serialization.token_prefix is now available.

• #127 e5c275f Thanks @bitjson! - Unify object parameters and error handling across library

  A number of existing Libauth utilities have been modified to adhere to Libauth's object parameter and error handling conventions:

  • CashAddress utilities:
    • encodeCashAddress/decodeCashAddress
    • lockingBytecodeToCashAddress/cashAddressToLockingBytecode
    • encodeCashAddressFormat/decodeCashAddressFormat
  • BIP32 (HD Key) utilities:
    • crackHdPrivateNodeFromHdPublicNodeAndChildPrivateNode
    • decodeHdKey (decodeHdKeyUnchecked)
    • decodeHdPrivateKey/encodeHdPrivateKey
    • decodeHdPublicKey/encodeHdPrivateKey
    • deriveHdPath
    • deriveHdPathRelative
    • deriveHdPrivateNodeFromSeed
    • deriveHdPrivateNodeIdentifier/deriveHdPublicNodeIdentifier
    • deriveHdPrivateNodeChild/deriveHdPublicNodeChild
    • deriveHdPublicKey
    • deriveHdPublicNode
    • hdKeyVersionIsPrivateKey/hdKeyVersionIsPublicKey
    • hdPrivateKeyToIdentifier/hdPublicKeyToIdentifier
  • BIP39 (Mnemonic Phrase) Utilities:
    • deriveHdPrivateNodeFromBip39Mnemonic
    • deriveSeedFromBip39Mnemonic
    • encodeBip39Mnemonic/decodeBip39Mnemonic
    • generateBip39Mnemonic
  • Key Utilities:
    • generateDeterministicEntropy

  Please see the relevant guide(s) for usage examples:

  • Handling Errors
  • Keys
  • Addresses
  • Wallets & Transaction Creation

Minor Changes

• #127 e5c275f Thanks @bitjson! - Add usage guides and API overview

• #127 e5c275f Thanks @bitjson! - Add P2PKH CashAddress utilities

  The following utilities are now available:

  • hdPrivateKeyToP2pkhLockingBytecode
  • hdPrivateKeyToP2pkhCashAddress
  • hdPublicKeyToP2pkhLockingBytecode
  • hdPublicKeyToP2pkhCashAddress
  • privateKeyToP2pkhLockingBytecode
  • privateKeyToP2pkhCashAddress
  • publicKeyToP2pkhLockingBytecode
  • publicKeyToP2pkhCashAddress

  For usage examples, see wallets.md.

• #127 e5c275f Thanks @bitjson! - Validate all keys prior to compilation, expose validateCompilationData

  The compiler now validates all compilation data (i.e. validate all public and private keys), prior to compilation, regardless of whether or not the offending public or private key material is used. This is intended to surface software defects (particularly in the software used by counterparties) as early as possible.

• #127 e5c275f Thanks @bitjson! - Add support for decodeTransactionOutputs

Patch Changes

• #127 e5c275f Thanks @bitjson! - generateRandomBytes: always verify unique results across two runs

  Fixes #119. Old behavior is available at generateRandomBytesUnchecked.

2.1.0

Minor Changes

• #117 8e032c2 Thanks @jimtendo! - Add PBKDF2 and BIP39 Support

Patch Changes

• #117 51c7ee3 Thanks @bitjson! - Use @changesets/cli, remove standard-version
• #117 7ddad21 Thanks @bitjson! - Publish with provenance via GitHub Actions

2.0.0

Libauth is now a pure ESM package, simplifying the developer experience by allowing WASM crypto to be instantiated internally/automatically by default 🎉. This refactor also simplifies the usage of and types surrounding Libauth virtual machines and compilers, and several other APIs have been improved.

New, dedicated Telegram channels are also available for Libauth release announcements and Libauth developer discussions.

Simplified Virtual Machine Types

Previously, Libauth VMs were very strictly-typed such that error messages and opcodes used chain-specific enums (e.g. AuthenticationErrorBCH and OpcodesBCH). While this configuration did ensure that VMs and VM results were strictly-typed with chain information, the configuration ultimately made library components much harder to remix without deep knowledge of TypeScript's type system. In both cases, such type information rarely catches downstream implementation bugs:

• Differing opcode enums effectively only narrow the real-time type from number to 0 | 1 | 2 | ... | 254 | 255.
• Differing error enums only offer a slight benefit in making error matching slightly simpler, and they present a significant disadvantage in that they preclude the contextualization of errors – each error string must be fully defined at compile time.

In both cases, the differing types offer only very marginal benefit at the cost of exceptional added complexity (widespread proliferation of generic types throughout the codebase). This refactor migrates the opcode type to number and the error type to string | undefined, leaving the opcode and error enums primarily as a form of documentation.

Simplified VM Usage

Transaction validation infrastructure is now a part of each VM instance, so transaction validation is as simple as vm.verify({ transaction, sourceOutputs }) (returning either true or an error string). This behavior offers individual VMs full control of transaction parsing and validation, allowing Libauth VMs to implement proposals for significant modifications like new transaction formats or high-level transaction validation changes.

Simplified VM Operations and Instruction Sets

Beginning with this version, Libauth will no longer maintain support for defunct VM versions. For example, BCH_2019_05 was an upgrade which enabled Schnorr signature support in CHECKSIG and CHECKDATASIG and a clean-stack exception for SegWit recovery. The BCH_2019_05 VM was replaced without a network split by the BCH_2019_11 upgrade, meaning BCH_2019_05 is no longer in use by any public network. As such, relevant code paths, flags, and other VM-specific functionality for BCH_2019_05 has been removed to simplify currently supported Libauth VMs. (Of course, historical implementations will always remain available in previously-released versions of Libauth.)

With this change, the existing VM implementations have been significantly simplified, removing unused code and reducing type complexity. Built-in VM instruction sets are now specified in a single file, making them easier to review and copy.

Additional Changes

Several other improvements have been made:

• Default crypto interface instances – because Libauth is now pure ESM, all of Libauth's WebAssembly cryptography implementations can now be automatically instantiated internally by the library. All Libauth methods that require crypto now use these automatically-instantiated implementations by default (as a default parameter), but consumers can opt-out of the behavior by providing a replacement implementation (and build tools that support dead code elimination/tree shaking of default parameters can automatically drop the unused crypto implementations.) To support this functionality, the parameter ordering of many functions have been modified to shift crypto implementations to the end (as optional parameters).
• Secp256k1 doesn't throw - the Secp256k1 interface previously threw errors, breaking from Libauth's convention of well-typed errors. All Secp256k1 methods now return error messages as strings where applicable.
• CashAssembly – is the new name for Bitauth Templating Language (BTL), the simple language used within Libauth templates.
• Consistent capitalization, miscellaneous corrections – some exports have been renamed to consistently use camelCase (for functions) or PascalCase (for types/interfaces), respectively. Several exports have been renamed for discoverability and consistency with other exports.
• Expanded state available to VMs and compilers – VM and compiler operations can now access all raw contents of transactions and source outputs.
• Expanded capabilities of template scenarios – scenarios can now represent any transaction shape and generate full, serializable transactions.
• New VM bytecode test vector generation – Libauth includes a new vmb_tests test vector generation system to produce sets of cross-implementation test vectors as serialized transactions; this allows for sets of test vectors that fully test all transaction validation infrastructure without making assumptions about implementation internals.
• Improved CashAddress utilities – cash address utilities no longer require enums, hash lengths are measured in bytes rather than bits, and type is distinguished from typeBit.
• More consistent encoding/decoding utilities – Several decoding methods have been renamed and refactored to use the new ReadPosition API.
• More consistent error handling – all possible errors are surfaced in type signatures as strings.

2.0.0-alpha.8 (2023-01-10)