coinstring

build status Coverage Status Version

browser support

JavaScript component that's used to generate relevant addresses, wallet import formats, BIP32 encodings, and base 58 check encoding used by various crypto currencies. The difference between this and base58 check encoding is not much other than base 58 check encoding specifies that the version should only have one byte. This means that base 58 check encoding technically would NOT work for BIP 32 addresses, but this module does work with BIP 32 addresses.

Works in Node.js and the browser.

Package Info

Installation

npm install coinstring --save

Examples

Note: You'd commonly use this package in conjunction with coininfo.

Convert Private Key to Bitcoin Wallet Import Format

var cs = require('coinstring')

var privateKeyHex = "1184cd2cdd640ca42cfc3a091c51d549b2f016d454b2774019c2b2d2e08529fd"
var privateKeyHexBuf = new Buffer(privateKeyHex, 'hex')
var version = 0x80; //Bitcoin private key

console.log(cs.encode(privateKeyHexBuf, version)) 
// => 5Hx15HFGyep2CfPxsJKe2fXJsCVn5DEiyoeGGF6JZjGbTRnqfiD

Convert hash160 (aka pubKeyHash) to Bitcoin Address

var cs = require('coinstring')

var hash160 = "3c176e659bea0f29a3e9bf7880c112b1b31b4dc8" //hash representing uncompressed
var hash160Buf = new Buffer(hash160, 'hex')
var version = 0x00; //Bitcoin public address

console.log(cs.encode(hash160Buf, version)); 
// => 16UjcYNBG9GTK4uq2f7yYEbuifqCzoLMGS

Convert Private Key to Compressed Bitcoin Wallet Import Format

var cs = require('coinstring')

var privateKeyHex = "1184cd2cdd640ca42cfc3a091c51d549b2f016d454b2774019c2b2d2e08529fd"

//for compressed, append "01"
privateKeyHex += '01'

var privateKeyHexBuf = new Buffer(privateKeyHex, 'hex')
var version = 0x80 //Bitcoin private key

console.log(cs.encode(privateKeyHexBuf, version))
// => KwomKti1X3tYJUUMb1TGSM2mrZk1wb1aHisUNHCQXTZq5auC2qc3

Convert hash160 (aka pubkeyhash) to Dogecoin Address

var cs = require('coinstring')

var hash160 = "3c176e659bea0f29a3e9bf7880c112b1b31b4dc8" //hash representing uncompressed
var hash160Buf = new Buffer(hash160, 'hex')
var version = 0x1E //Dogecoin public address

console.log(cs.encode(hash160Buf, version)) 
// => DAcq9oJpZZAjr56RmF7Y5zmWboZWQ4HAsW

Encode BIP 32 Bitcoin Private Key

Base 58 check encoding cannot typically enocde these since it requires the version to only be one byte. Read more about BIP32 here.

var cs = require('coinstring')

var data = "000000000000000000873dff81c02f525623fd1fe5167eac3a55a049de3d314bb42ee227ffed37d50800e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35" 
var buffer = new Buffer(data, 'hex')
var version = new Buffer('0488ade4', 'hex') //0488ade4 is a consant listed in the aforementioned bip32 wiki.

console.log(cs.encode(buffer, version)) 
// => xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi

Decode Bitcoin Private Wallet Import Format (WIF) to private key

var cs = require('coinstring')

var res = cs.decode('5Hx15HFGyep2CfPxsJKe2fXJsCVn5DEiyoeGGF6JZjGbTRnqfiD')
console.log(res.version.toString('hex')) // => 80
console.log(res.payload.toString('hex')) // => 1184cd2cdd640ca42cfc3a091c51d549b2f016d454b2774019c2b2d2e08529fd

Functional Goodies

coinstring also has some functional goodies.

Function to Generate Bitcoin Wallet Import Format

var cs = require('coinstring')

var privateKeyHex = "1184cd2cdd640ca42cfc3a091c51d549b2f016d454b2774019c2b2d2e08529fd";
var privateKeyHexBuf = new Buffer(privateKeyHex, 'hex')
var version = 0x80 //Bitcoin private key

var toBtcWif = cs.createEncoder(version)

//later in your program
console.log(toBtcWif(privateKeyHexBuf)) 
// => 5Hx15HFGyep2CfPxsJKe2fXJsCVn5DEiyoeGGF6JZjGbTRnqfiD

Function to Parse Bitcoin Wallet Import Format

var cs = require('coinstring');

var wif = "5Hx15HFGyep2CfPxsJKe2fXJsCVn5DEiyoeGGF6JZjGbTRnqfiD"
var version = 0x80 //Bitcoin private key

var fromBtcWif = cs.createDecoder(version)

//later in your program
console.log(fromBtcWif(wif).payload.toString('hex')) 
// => 51184cd2cdd640ca42cfc3a091c51d549b2f016d454b2774019c2b2d2e08529fd

Function to Validate Bitcoin Testnet Addresses

var cs = require('coinstring');

var hash160 = "3c176e659bea0f29a3e9bf7880c112b1b31b4dc8" //hash representing uncompressed
var hash160Buf = new Buffer(hash160, 'hex')
var version = 0x6F //Bitcoin Testnet Address

var testnetAddressValidator = cs.createValidator(version)
console.log(testnetAddressValidator("mkzgubTA5Ahi6BPSkE6MN9pEafRutznkMe")) // => true

API

coinstring exports the following six functions:

encode(payload, [version])

Used to convert either a hash160 or private key into an address or wallet import format string respectively.

Returns the base58 encoded value of type string.

decode(base58str, [version])

It is the inverse of the encode() function i.e. it converts the address or wallet import format into a Buffer of bytes. It throws if the address or wallet import format is not valid. Not valid means that the version doesn't match, or the checksum is incorrect.

Returns the decoded base58 payload of type Buffer. If version was passed to input, it is chopped off on the output.

isValid(base58str, version)

Validates whether the address string or wallet import format string is valid.

Returns a true or false.

createEncoder(version)

Returns a function that takes as input the payload like from encode() above.

createDecoder(version)

Returns a function that takes as input the base58str like from decode() above.

createValidator(version)

Returns a function that takes as input the base58str like from isValid() above.

List of Common Crypto Currency Versions

The following is a table of common crypto currency versions. It may seem a bit user unfriendly to have to input the number instead of something like "BTC"; we agree. Another module will be created to address this. In the meantime, use the table below.

Crypto CoinPublic AddressPrivate Wallet Import Format
Bitcoin 0x00 0x80
Bitcoin Script Hash 0x05 N/A
Bitcoin Testnet 0x6E 0xEF
Bitcoin Testnet Script Hash 0xC4 N/A
Dogecoin 0x1E 0x9E
Litecoin 0x30 0xB0
Namecoin 0x34 0xB4

You may also want to just use the module coininfo instead.

References