UNPKG

bchaddrjs/README.md

Version:

5.11 kBMarkdownView Raw

1# BchAddr.js: Bitcoin Cash general purpose address translation for Node.js and web browsers.
2
3[![Build Status](https://travis-ci.org/bitcoincashjs/bchaddrjs.svg?branch=master)](https://travis-ci.org/bitcoincashjs/bchaddrjs) [![Coverage Status](https://coveralls.io/repos/github/bitcoincashjs/bchaddrjs/badge.svg?branch=master)](https://coveralls.io/github/bitcoincashjs/bchaddrjs?branch=master)
4[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
5
6[![NPM](https://nodei.co/npm/bchaddrjs.png?downloads=true)](https://nodei.co/npm/bchaddrjs/)
7
8[![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
9
10Plug & Play JavaScript library for all Bitcoin Cash address format translation needs. Easy-to-use, thoroughly tested, and feature complete.
11
12Support for the new Bitcoin Cash address [format](https://github.com/Bitcoin-UAHF/spec/blob/master/bchaddr.md) which improves upon [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki), as well as the Bitpay and Legacy formats.
13
14Test out a demo address translator powered by BchAddr.js [here](https://bitcoincashjs.github.io/address/).
15
16## Installation
17
18### Using NPM
19
20```bsh
21$ npm install --save bchaddrjs
22```
23
24### Using Bower
25
26```bsh
27$ bower install --save bchaddrjs
28```
29
30### Manually
31
32You may also download the distribution file manually and place it within your third-party scripts directory: [dist/bchaddrjs-0.1.4.min.js](https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/dist/bchaddrjs-0.1.4.min.js).
33
34## Usage
35
36### In Node.js
37
38```javascript
39var bchaddr = require('bchaddrjs');
40```
41
42### Browser
43
44#### Script Tag
45
46You may include a script tag in your HTML and the `bchaddr` module will be defined globally on subsequent scripts.
47
48```html
49<html>
50  <head>
51    ...
52    <script src="https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/dist/bchaddrjs-0.1.4.min.js"></script>
53  </head>
54  ...
55</html>
56```
57
58## Code Examples
59
60### Supported formats, networks and address types.
61```javascript
62var Format = bchaddr.Format; // Legacy, Bitpay or Cashaddr.
63var Network = bchaddr.Network; // Mainnet or Testnet.
64var Type = bchaddr.Type; // P2PKH or P2SH.
65```
66
67### Test for address format.
68```javascript
69var isLegacyAddress = bchaddr.isLegacyAddress;
70var isBitpayAddress = bchaddr.isBitpayAddress;
71var isCashAddress = bchaddr.isCashAddress;
72
73isLegacyAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // true
74isLegacyAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // false
75isBitpayAddress('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // true
76isBitpayAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // false
77isCashAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // true
78isCashAddress('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // false
79```
80
81### Test for address network.
82```javascript
83var isMainnetAddress = bchaddr.isMainnetAddress;
84var isTestnetAddress = bchaddr.isTestnetAddress;
85
86isMainnetAddress('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // true
87isMainnetAddress('mnbGP2FeRsbgdQCzDT35zPWDcYSKm4wrcg') // false
88isTestnetAddress('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // true
89isTestnetAddress('CeUvhjLnSgcxyedaUafcyo4Cw9ZPwGq9JJ') // false
90```
91
92### Test for address type.
93```javascript
94var isP2PKHAddress = bchaddr.isP2PKHAddress;
95var isP2SHAddress = bchaddr.isP2SHAddress;
96
97isP2PKHAddress('1Mdob5JY1yuwoj6y76Vf3AQpoqUH5Aft8z') // true
98isP2PKHAddress('2NFGG7yRBizUANU48b4dASrnNftqsNwzSM1') // false
99isP2SHAddress('H92i9XpREZiBscxGu6Vx3M8jNGBKqscBBB') // true
100isP2SHAddress('CeUvhjLnSgcxyedaUafcyo4Cw9ZPwGq9JJ') // false
101```
102
103### Detect address format.
104```javascript
105var detectAddressFormat = bchaddr.detectAddressFormat;
106
107detectAddressFormat('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // Format.Cashaddr
108detectAddressFormat('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // Format.Bitpay
109```
110
111### Detect address network.
112```javascript
113var detectAddressNetwork = bchaddr.detectAddressNetwork;
114
115detectAddressNetwork('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // Network.Mainnet
116detectAddressNetwork('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // Network.Testnet
117```
118
119### Detect address type.
120```javascript
121var detectAddressType = bchaddr.detectAddressType;
122
123detectAddressType('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // Type.P2PKH
124detectAddressType('3NKpWcnyZtEKttoQECAFTnmkxMkzgbT4WX') // Type.P2SH
125```
126
127### Translate address from any address format into a specific format.
128```javascript
129var toLegacyAddress = bchaddr.toLegacyAddress;
130var toBitpayAddress = bchaddr.toBitpayAddress;
131var toCashAddress = bchaddr.toCashAddress;
132
133toLegacyAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // 1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR
134toBitpayAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj
135toCashAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // bitcoincash:qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk
136```
137
138## Documentation
139
140### Generate and Browse Locally
141
142```bsh
143$ npm run docs
144```
145
146### Online
147
148Browse automatically generated jsdocs [online](https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/jsdoc/index.html).

1	`# BchAddr.js: Bitcoin Cash general purpose address translation for Node.js and web browsers.`
2
3	`[![Build Status](https://travis-ci.org/bitcoincashjs/bchaddrjs.svg?branch=master)](https://travis-ci.org/bitcoincashjs/bchaddrjs) [![Coverage Status](https://coveralls.io/repos/github/bitcoincashjs/bchaddrjs/badge.svg?branch=master)](https://coveralls.io/github/bitcoincashjs/bchaddrjs?branch=master)`
4	`[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)`
5
6	`[![NPM](https://nodei.co/npm/bchaddrjs.png?downloads=true)](https://nodei.co/npm/bchaddrjs/)`
7
8	`[![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)`
9
10	`Plug & Play JavaScript library for all Bitcoin Cash address format translation needs. Easy-to-use, thoroughly tested, and feature complete.`
11
12	`Support for the new Bitcoin Cash address [format](https://github.com/Bitcoin-UAHF/spec/blob/master/bchaddr.md) which improves upon [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki), as well as the Bitpay and Legacy formats.`
13
14	`Test out a demo address translator powered by BchAddr.js [here](https://bitcoincashjs.github.io/address/).`
15
16	`## Installation`
17
18	`### Using NPM`
19
20	```bsh
21	`$ npm install --save bchaddrjs`
22	```
23
24	`### Using Bower`
25
26	```bsh
27	`$ bower install --save bchaddrjs`
28	```
29
30	`### Manually`
31
32	`You may also download the distribution file manually and place it within your third-party scripts directory: [dist/bchaddrjs-0.1.4.min.js](https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/dist/bchaddrjs-0.1.4.min.js).`
33
34	`## Usage`
35
36	`### In Node.js`
37
38	```javascript
39	`var bchaddr = require('bchaddrjs');`
40	```
41
42	`### Browser`
43
44	`#### Script Tag`
45
46	You may include a script tag in your HTML and the `bchaddr` module will be defined globally on subsequent scripts.
47
48	```html
49	`<html>`
50	`<head>`
51	`...`
52	`<script src="https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/dist/bchaddrjs-0.1.4.min.js"></script>`
53	`</head>`
54	`...`
55	`</html>`
56	```
57
58	`## Code Examples`
59
60	`### Supported formats, networks and address types.`
61	```javascript
62	`var Format = bchaddr.Format; // Legacy, Bitpay or Cashaddr.`
63	`var Network = bchaddr.Network; // Mainnet or Testnet.`
64	`var Type = bchaddr.Type; // P2PKH or P2SH.`
65	```
66
67	`### Test for address format.`
68	```javascript
69	`var isLegacyAddress = bchaddr.isLegacyAddress;`
70	`var isBitpayAddress = bchaddr.isBitpayAddress;`
71	`var isCashAddress = bchaddr.isCashAddress;`
72
73	`isLegacyAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // true`
74	`isLegacyAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // false`
75	`isBitpayAddress('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // true`
76	`isBitpayAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // false`
77	`isCashAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // true`
78	`isCashAddress('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // false`
79	```
80
81	`### Test for address network.`
82	```javascript
83	`var isMainnetAddress = bchaddr.isMainnetAddress;`
84	`var isTestnetAddress = bchaddr.isTestnetAddress;`
85
86	`isMainnetAddress('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // true`
87	`isMainnetAddress('mnbGP2FeRsbgdQCzDT35zPWDcYSKm4wrcg') // false`
88	`isTestnetAddress('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // true`
89	`isTestnetAddress('CeUvhjLnSgcxyedaUafcyo4Cw9ZPwGq9JJ') // false`
90	```
91
92	`### Test for address type.`
93	```javascript
94	`var isP2PKHAddress = bchaddr.isP2PKHAddress;`
95	`var isP2SHAddress = bchaddr.isP2SHAddress;`
96
97	`isP2PKHAddress('1Mdob5JY1yuwoj6y76Vf3AQpoqUH5Aft8z') // true`
98	`isP2PKHAddress('2NFGG7yRBizUANU48b4dASrnNftqsNwzSM1') // false`
99	`isP2SHAddress('H92i9XpREZiBscxGu6Vx3M8jNGBKqscBBB') // true`
100	`isP2SHAddress('CeUvhjLnSgcxyedaUafcyo4Cw9ZPwGq9JJ') // false`
101	```
102
103	`### Detect address format.`
104	```javascript
105	`var detectAddressFormat = bchaddr.detectAddressFormat;`
106
107	`detectAddressFormat('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // Format.Cashaddr`
108	`detectAddressFormat('CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj') // Format.Bitpay`
109	```
110
111	`### Detect address network.`
112	```javascript
113	`var detectAddressNetwork = bchaddr.detectAddressNetwork;`
114
115	`detectAddressNetwork('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // Network.Mainnet`
116	`detectAddressNetwork('qqdcsl6c879esyxyacmz7g6vtzwjjwtznsggspc457') // Network.Testnet`
117	```
118
119	`### Detect address type.`
120	```javascript
121	`var detectAddressType = bchaddr.detectAddressType;`
122
123	`detectAddressType('1P238gziZdeS5Wj9nqLhQHSBK2Lz6zPSke') // Type.P2PKH`
124	`detectAddressType('3NKpWcnyZtEKttoQECAFTnmkxMkzgbT4WX') // Type.P2SH`
125	```
126
127	`### Translate address from any address format into a specific format.`
128	```javascript
129	`var toLegacyAddress = bchaddr.toLegacyAddress;`
130	`var toBitpayAddress = bchaddr.toBitpayAddress;`
131	`var toCashAddress = bchaddr.toCashAddress;`
132
133	`toLegacyAddress('qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk') // 1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR`
134	`toBitpayAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // CScMwvXjdooDnGevHgfHjGWFi9cjk75Aaj`
135	`toCashAddress('1B9UNtBfkkpgt8kVbwLN9ktE62QKnMbDzR') // bitcoincash:qph5kuz78czq00e3t85ugpgd7xmer5kr7c5f6jdpwk`
136	```
137
138	`## Documentation`
139
140	`### Generate and Browse Locally`
141
142	```bsh
143	`$ npm run docs`
144	```
145
146	`### Online`
147
148	`Browse automatically generated jsdocs [online](https://cdn.rawgit.com/bitcoincashjs/bchaddrjs/master/jsdoc/index.html).`