Bitcoin Address

Represents a bitcoin address. Addresses are the most popular way to make bitcoin transactions. See the official Bitcoin Wiki for technical background information.

Instantiate an Address

To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Please take a look at the PrivateKey docs for more information about exporting and saving a key.

var privateKey = new PrivateKey();
var address = privateKey.toAddress();

You can also instantiate an Address from a String, PublicKey, or HDPublicKey, in case you are not the owner of the private key.

// from a string
var address = Address.fromString('mwkXG8NnB2snbqWTcpNiK6qqGHm1LebHDc');

// a default network address from a public key
var publicKey = PublicKey(privateKey);
var address = new Address(publicKey);
// alternative interface
var address = Address.fromPublicKey(publicKey);

// a testnet address from a public key
var publicKey = new PublicKey(privateKey);
var address = new Address(publicKey, Networks.testnet);

A pay-to-script-hash multisignature Address can be instantiated from an array of PublicKeys.

// a 2-of-3 address from public keys
var p2shAddress = new Address([publicKey1, publicKey2, publicKey3], 2);

Validating an Address

The main use that we expect you'll have for the Address class in Bitcore is validating that an address is a valid one, what type of address it is (you may be interested on knowing if the address is a simple "pay to public key hash" address or a "pay to script hash" address) and what network does the address belong to.

The code to do these validations looks like this:

// validate an address
if (Address.isValid(input){
  ...
}

// validate that an input field is a valid testnet address
if (Address.isValid(input, Networks.testnet){
  ...
}

// validate that an input field is a valid livenet pubkeyhash
if (Address.isValid(input, Networks.livenet, Address.PayToPublicKeyHash){
  ...
}

// get the specific validation error that can occurred
var error = Address.getValidationError(input, Networks.testnet);
  if (error) {
    // handle the error
  }
}

The errors are listed in the generated file in the errors folder. There's a structure to errors defined in the spec.js file.

Address

Kind: global class

new Address(data, network, [type])

Instantiate an address from an address String or Buffer, a public key or script hash Buffer, or an instance of PublicKey or Script.

This is an immutable class, and if the first parameter provided to this constructor is an Address instance, the same argument will be returned.

An address has two key properties: network and type. The type is either Address.PayToPublicKeyHash (value is the 'pubkeyhash' string) or Address.PayToScriptHash (the string 'scripthash'). The network is an instance of Network. You can quickly check whether an address is of a given kind by using the methods isPayToPublicKeyHash and isPayToScriptHash

Returns: Address - A new valid and frozen instance of an Address

Param Type Description
data * The encoded data in various formats
network Network | String | number The network: 'livenet' or 'testnet'
[type] string The type of address: 'script' or 'pubkey'

Example

// validate that an input field is valid
var error = Address.getValidationError(input, 'testnet');
if (!error) {
  var address = Address(input, 'testnet');
} else {
  // invalid network or checksum (typo?)
  var message = error.messsage;
}

// get an address from a public key
var address = Address(publicKey, 'testnet').toString();

address.toObject ⇒ Object

Kind: instance property of Address
Returns: Object - A plain object with the address information

address._classifyArguments(data, network, [type]) ⇒ Object

Internal function used to split different kinds of arguments of the constructor

Kind: instance method of Address
Returns: Object - An "info" object with "type", "network", and "hashBuffer"

Param Type Description
data * The encoded data in various formats
network Network | String | number The network: 'livenet' or 'testnet'
[type] string The type of address: 'script' or 'pubkey'

address.isPayToPublicKeyHash() ⇒

Returns true if an address is of pay to public key hash type

Kind: instance method of Address
Returns: boolean

address.isPayToScriptHash() ⇒

Returns true if an address is of pay to script hash type

Kind: instance method of Address
Returns: boolean

address.toBuffer() ⇒ Buffer

Will return a buffer representation of the address

Kind: instance method of Address
Returns: Buffer - Bitcoin address buffer

address.toString() ⇒ string

Will return a the string representation of the address

Kind: instance method of Address
Returns: string - Bitcoin address

address.inspect() ⇒ string

Will return a string formatted for the console

Kind: instance method of Address
Returns: string - Bitcoin address

Address.PayToPublicKeyHash

Kind: static property of Address

Address.PayToScriptHash

Kind: static property of Address

Address._transformObject(data) ⇒ Address

Deserializes an address serialized through Address#toObject()

Kind: static method of Address

Param Type Description
data Object
data.hash string the hash that this address encodes
data.type string either 'pubkeyhash' or 'scripthash'
[data.network] Network the name of the network associated

Address.createMultisig(publicKeys, threshold, network) ⇒ Address

Creates a P2SH address from a set of public keys and a threshold.

The addresses will be sorted lexicographically, as that is the trend in bitcoin. To create an address from unsorted public keys, use the Script#buildMultisigOut interface.

Kind: static method of Address

Param Type Description
publicKeys Array a set of public keys to create an address
threshold number the number of signatures needed to release the funds
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.fromPublicKey(data, network) ⇒ Address

Instantiate an address from a PublicKey instance

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
data PublicKey
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.fromPublicKeyHash(hash, network) ⇒ Address

Instantiate an address from a ripemd160 public key hash

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
hash Buffer An instance of buffer of the hash
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.fromScriptHash(hash, network) ⇒ Address

Instantiate an address from a ripemd160 script hash

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
hash Buffer An instance of buffer of the hash
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.payingTo(script, network) ⇒ Address

Builds a p2sh address paying to script. This will hash the script and use that to create the address. If you want to extract an address associated with a script instead, see {{Address#fromScript}}

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
script Script An instance of Script
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.fromScript(script, network) ⇒ Address

Extract address from a Script. The script must be of one of the following types: p2pkh input, p2pkh output, p2sh input or p2sh output. This will analyze the script and extract address information from it. If you want to transform any script to a p2sh Address paying to that script's hash instead, use {{Address#payingTo}}

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
script Script An instance of Script
network String | Network either a Network instance, 'livenet', or 'testnet'

Address.fromBuffer(buffer, network, [type]) ⇒ Address

Instantiate an address from a buffer of the address

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
buffer Buffer An instance of buffer of the address
network String | Network either a Network instance, 'livenet', or 'testnet'
[type] string The type of address: 'script' or 'pubkey'

Address.fromString(str, network, [type]) ⇒ Address

Instantiate an address from an address string

Kind: static method of Address
Returns: Address - A new valid and frozen instance of an Address

Param Type Description
str string An string of the bitcoin address
network String | Network either a Network instance, 'livenet', or 'testnet'
[type] string The type of address: 'script' or 'pubkey'

Address.fromObject(json) ⇒ Address

Instantiate an address from an Object

Kind: static method of Address
Returns: Address - A new valid instance of an Address

Param Type Description
json string An JSON string or Object with keys: hash, network and type

Address.getValidationError(data, network, type) ⇒ null | Error

Will return a validation error if exists

Kind: static method of Address
Returns: null | Error - The corresponding error message

Param Type Description
data string The encoded data
network String | Network either a Network instance, 'livenet', or 'testnet'
type string The type of address: 'script' or 'pubkey'

Example

// a network mismatch error
var error = Address.getValidationError('15vkcKf7gB23wLAnZLmbVuMiiVDc1Nm4a2', 'testnet');

Address.isValid(data, network, type) ⇒ boolean

Will return a boolean if an address is valid

Kind: static method of Address
Returns: boolean - The corresponding error message

Param Type Description
data string The encoded data
network String | Network either a Network instance, 'livenet', or 'testnet'
type string The type of address: 'script' or 'pubkey'

Example

assert(Address.isValid('15vkcKf7gB23wLAnZLmbVuMiiVDc1Nm4a2', 'livenet'));