Skip to content

Commit 6463bbc

Browse files
jasonandjayjasonandjay
committed
📄 docs: build src after comment address namespace
1 parent 5382260 commit 6463bbc

File tree

6 files changed

+305
-0
lines changed

6 files changed

+305
-0
lines changed

‎src/address.d.ts‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,170 @@
11
/// <reference types="node" />
2+
/**
3+
* bitcoin address decode and encode tools, include base58、bech32 and output script
4+
*
5+
* networks support bitcoin、litecoin、bitcoin testnet、litecoin testnet、bitcoin regtest、litecoin regtest and so on
6+
*
7+
* addresses support P2PKH、P2SH、P2WPKH、P2WSH、P2TR and so on
8+
*
9+
* @packageDocumentation
10+
*/
211
import { Network } from './networks';
12+
/** base58check decode result */
313
export interface Base58CheckResult {
14+
/** address hash */
415
hash: Buffer;
16+
/** address version: 0x00 for P2PKH, 0x05 for P2SH */
517
version: number;
618
}
19+
/** bech32 decode result */
720
export interface Bech32Result {
21+
/** address version: 0x00 for P2WPKH、P2WSH, 0x01 for P2TR*/
822
version: number;
23+
/** address prefix: bc for P2WPKH、P2WSH、P2TR */
924
prefix: string;
25+
/** address data：20 bytes for P2WPKH, 32 bytes for P2WSH、P2TR */
1026
data: Buffer;
1127
}
28+
/**
29+
* decode address with base58 specification, return address version and address hash if valid
30+
* @example
31+
* ```ts
32+
* // valid case
33+
* fromBase58Check('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH')
34+
* // => {version: 0, hash: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
35+
*
36+
* // invalid case: address is too short
37+
* fromBase58Check('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx')
38+
* // => throw new TypeError('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx is too short')
39+
*
40+
* // invalid case: address is too long
41+
* fromBase58Check('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe')
42+
* // => throw new TypeError('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe is too long')
43+
* ```
44+
*/
1245
export declare function fromBase58Check(address: string): Base58CheckResult;
46+
/**
47+
* decode address with bech32 specification, return address version、address prefix and address data if valid
48+
* @example
49+
* ```ts
50+
* // valid case
51+
* fromBech32('BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4')
52+
* // => {version: 0, prefix: 'bc', data: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
53+
*
54+
* // invalid case
55+
* fromBase58Check('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5')
56+
* // => Invalid checksum
57+
*
58+
* // invalid case
59+
* fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sL5k7')
60+
* // => Mixed-case string
61+
*
62+
* // invalid case
63+
* fromBase58Check('tb1pw508d6qejxtdg4y5r3zarquvzkan')
64+
* // => Excess padding
65+
*
66+
* // invalid case
67+
* fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
68+
* // => Excess padding
69+
*
70+
* // invalid case
71+
* fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
72+
* // => Non-zero padding
73+
*
74+
* // invalid case
75+
* fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3pjxtptv')
76+
* // => uses wrong encoding
77+
*
78+
* // invalid case
79+
* fromBase58Check('bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqh2y7hd')
80+
* // => uses wrong encoding
81+
* ```
82+
*/
1383
export declare function fromBech32(address: string): Bech32Result;
84+
/**
85+
* encode address hash to base58 address with version
86+
*
87+
* @example
88+
* ```ts
89+
* // valid case
90+
* toBase58Check('751e76e8199196d454941c45d1b3a323f1433bd6', 0)
91+
* // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
92+
* ```
93+
*/
1494
export declare function toBase58Check(hash: Buffer, version: number): string;
95+
/**
96+
* encode address hash to bech32 address with version and prefix
97+
*
98+
* @example
99+
* ```ts
100+
* // valid case
101+
* toBech32('000000c4a5cad46221b2a187905e5266362b99d5e91c6ce24d165dab93e86433', 0, 'tb)
102+
* // => tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy
103+
* ```
104+
*/
15105
export declare function toBech32(data: Buffer, version: number, prefix: string): string;
106+
/**
107+
* decode address from output script with network, return address if matched
108+
* @example
109+
* ```ts
110+
* // valid case
111+
* fromOutputScript('OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG', 'bicoin)
112+
* // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
113+
*
114+
* // invalid case
115+
* fromOutputScript('031f1e68f82112b373f0fe980b3a89d212d2b5c01fb51eb25acb8b4c4b4299ce95 OP_CHECKSIG', undefined)
116+
* // => has no matching Address
117+
*
118+
* // invalid case
119+
* fromOutputScript('OP_TRUE 032487c2a32f7c8d57d2a93906a6457afd00697925b0e6e145d89af6d3bca33016 02308673d16987eaa010e540901cc6fe3695e758c19f46ce604e174dac315e685a OP_2 OP_CHECKMULTISIG', undefined)
120+
* // => has no matching Address
121+
*
122+
* // invalid case
123+
* fromOutputScript('OP_RETURN 06deadbeef03f895a2ad89fb6d696497af486cb7c644a27aa568c7a18dd06113401115185474', undefined)
124+
* // => has no matching Address
125+
*
126+
* // invalid case
127+
* fromOutputScript('OP_0 75', undefined)
128+
* // => has no matching Address
129+
*
130+
* // invalid case
131+
* fromOutputScript('OP_0 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
132+
* // => has no matching Address
133+
*
134+
* // invalid case
135+
* fromOutputScript('OP_1 75', undefined)
136+
* // => has no matching Address
137+
*
138+
* // invalid case
139+
* fromOutputScript('OP_1 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
140+
* // => has no matching Address
141+
*
142+
* // invalid case
143+
* fromOutputScript('OP_1 fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f', undefined)
144+
* // => has no matching Address
145+
*
146+
* ```
147+
*/
16148
export declare function fromOutputScript(output: Buffer, network?: Network): string;
149+
/**
150+
* encodes address to output script with network, return output script if address matched
151+
* @example
152+
* ```ts
153+
* // valid case
154+
* toOutputScript('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH', 'bicoin)
155+
* // => OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG
156+
*
157+
* // invalid case
158+
* toOutputScript('24kPZCmVgzfkpGdXExy56234MRHrsqQxNWE', undefined)
159+
* // => has no matching Script
160+
*
161+
* // invalid case
162+
* toOutputScript('BC1SW50QGDZ25J', { "bech32": "foo" })
163+
* // => has an invalid prefix
164+
*
165+
* // invalid case
166+
* toOutputScript('bc1rw5uspcuh', undefined)
167+
* // => has no matching Script
168+
* ```
169+
*/
17170
export declare function toOutputScript(address: string, network?: Network): Buffer;

‎src/address.js‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,23 @@ function _toFutureSegwitAddress(output, network) {
4141
console.warn(FUTURE_SEGWIT_VERSION_WARNING);
4242
return toBech32(data, version, network.bech32);
4343
}
44+
/**
45+
* decode address with base58 specification, return address version and address hash if valid
46+
* @example
47+
* ```ts
48+
* // valid case
49+
* fromBase58Check('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH')
50+
* // => {version: 0, hash: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
51+
*
52+
* // invalid case: address is too short
53+
* fromBase58Check('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx')
54+
* // => throw new TypeError('7SeEnXWPaCCALbVrTnszCVGfRU8cGfx is too short')
55+
*
56+
* // invalid case: address is too long
57+
* fromBase58Check('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe')
58+
* // => throw new TypeError('j9ywUkWg2fTQrouxxh5rSZhRvrjMkEUfuiKe is too long')
59+
* ```
60+
*/
4461
function fromBase58Check(address) {
4562
const payload = Buffer.from(bs58check.decode(address));
4663
// TODO: 4.0.0, move to "toOutputScript"
@@ -51,6 +68,43 @@ function fromBase58Check(address) {
5168
return { version, hash };
5269
}
5370
exports.fromBase58Check = fromBase58Check;
71+
/**
72+
* decode address with bech32 specification, return address version、address prefix and address data if valid
73+
* @example
74+
* ```ts
75+
* // valid case
76+
* fromBech32('BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4')
77+
* // => {version: 0, prefix: 'bc', data: <Buffer 75 1e 76 e8 19 91 96 d4 54 94 1c 45 d1 b3 a3 23 f1 43 3b d6>}
78+
*
79+
* // invalid case
80+
* fromBase58Check('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5')
81+
* // => Invalid checksum
82+
*
83+
* // invalid case
84+
* fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sL5k7')
85+
* // => Mixed-case string
86+
*
87+
* // invalid case
88+
* fromBase58Check('tb1pw508d6qejxtdg4y5r3zarquvzkan')
89+
* // => Excess padding
90+
*
91+
* // invalid case
92+
* fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
93+
* // => Excess padding
94+
*
95+
* // invalid case
96+
* fromBase58Check('bc1zw508d6qejxtdg4y5r3zarvaryvq37eag7')
97+
* // => Non-zero padding
98+
*
99+
* // invalid case
100+
* fromBase58Check('tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3pjxtptv')
101+
* // => uses wrong encoding
102+
*
103+
* // invalid case
104+
* fromBase58Check('bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqh2y7hd')
105+
* // => uses wrong encoding
106+
* ```
107+
*/
54108
function fromBech32(address) {
55109
let result;
56110
let version;
@@ -73,6 +127,16 @@ function fromBech32(address) {
73127
};
74128
}
75129
exports.fromBech32 = fromBech32;
130+
/**
131+
* encode address hash to base58 address with version
132+
*
133+
* @example
134+
* ```ts
135+
* // valid case
136+
* toBase58Check('751e76e8199196d454941c45d1b3a323f1433bd6', 0)
137+
* // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
138+
* ```
139+
*/
76140
function toBase58Check(hash, version) {
77141
(0, types_1.typeforce)(
78142
(0, types_1.tuple)(types_1.Hash160bit, types_1.UInt8),
@@ -84,6 +148,16 @@ function toBase58Check(hash, version) {
84148
return bs58check.encode(payload);
85149
}
86150
exports.toBase58Check = toBase58Check;
151+
/**
152+
* encode address hash to bech32 address with version and prefix
153+
*
154+
* @example
155+
* ```ts
156+
* // valid case
157+
* toBech32('000000c4a5cad46221b2a187905e5266362b99d5e91c6ce24d165dab93e86433', 0, 'tb)
158+
* // => tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy
159+
* ```
160+
*/
87161
function toBech32(data, version, prefix) {
88162
const words = bech32_1.bech32.toWords(data);
89163
words.unshift(version);
@@ -92,6 +166,48 @@ function toBech32(data, version, prefix) {
92166
: bech32_1.bech32m.encode(prefix, words);
93167
}
94168
exports.toBech32 = toBech32;
169+
/**
170+
* decode address from output script with network, return address if matched
171+
* @example
172+
* ```ts
173+
* // valid case
174+
* fromOutputScript('OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG', 'bicoin)
175+
* // => 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
176+
*
177+
* // invalid case
178+
* fromOutputScript('031f1e68f82112b373f0fe980b3a89d212d2b5c01fb51eb25acb8b4c4b4299ce95 OP_CHECKSIG', undefined)
179+
* // => has no matching Address
180+
*
181+
* // invalid case
182+
* fromOutputScript('OP_TRUE 032487c2a32f7c8d57d2a93906a6457afd00697925b0e6e145d89af6d3bca33016 02308673d16987eaa010e540901cc6fe3695e758c19f46ce604e174dac315e685a OP_2 OP_CHECKMULTISIG', undefined)
183+
* // => has no matching Address
184+
*
185+
* // invalid case
186+
* fromOutputScript('OP_RETURN 06deadbeef03f895a2ad89fb6d696497af486cb7c644a27aa568c7a18dd06113401115185474', undefined)
187+
* // => has no matching Address
188+
*
189+
* // invalid case
190+
* fromOutputScript('OP_0 75', undefined)
191+
* // => has no matching Address
192+
*
193+
* // invalid case
194+
* fromOutputScript('OP_0 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
195+
* // => has no matching Address
196+
*
197+
* // invalid case
198+
* fromOutputScript('OP_1 75', undefined)
199+
* // => has no matching Address
200+
*
201+
* // invalid case
202+
* fromOutputScript('OP_1 751e76e8199196d454941c45d1b3a323f1433bd6751e76e8199196d454941c45d1b3a323f1433bd675', undefined)
203+
* // => has no matching Address
204+
*
205+
* // invalid case
206+
* fromOutputScript('OP_1 fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f', undefined)
207+
* // => has no matching Address
208+
*
209+
* ```
210+
*/
95211
function fromOutputScript(output, network) {
96212
// TODO: Network
97213
network = network || networks.bitcoin;
@@ -116,6 +232,27 @@ function fromOutputScript(output, network) {
116232
throw new Error(bscript.toASM(output) + ' has no matching Address');
117233
}
118234
exports.fromOutputScript = fromOutputScript;
235+
/**
236+
* encodes address to output script with network, return output script if address matched
237+
* @example
238+
* ```ts
239+
* // valid case
240+
* toOutputScript('1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH', 'bicoin)
241+
* // => OP_DUP OP_HASH160 751e76e8199196d454941c45d1b3a323f1433bd6 OP_EQUALVERIFY OP_CHECKSIG
242+
*
243+
* // invalid case
244+
* toOutputScript('24kPZCmVgzfkpGdXExy56234MRHrsqQxNWE', undefined)
245+
* // => has no matching Script
246+
*
247+
* // invalid case
248+
* toOutputScript('BC1SW50QGDZ25J', { "bech32": "foo" })
249+
* // => has an invalid prefix
250+
*
251+
* // invalid case
252+
* toOutputScript('bc1rw5uspcuh', undefined)
253+
* // => has no matching Script
254+
* ```
255+
*/
119256
function toOutputScript(address, network) {
120257
network = network || networks.bitcoin;
121258
let decodeBase58;

‎src/index.d.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,15 @@ import * as payments from './payments';
55
import * as script from './script';
66
export { address, crypto, networks, payments, script };
77
export { Block } from './block';
8+
/** @hidden */
89
export { TaggedHashPrefix } from './crypto';
910
export { Psbt, PsbtTxInput, PsbtTxOutput, Signer, SignerAsync, HDSigner, HDSignerAsync, } from './psbt';
11+
/** @hidden */
1012
export { OPS as opcodes } from './ops';
1113
export { Transaction } from './transaction';
14+
/** @hidden */
1215
export { Network } from './networks';
16+
/** @hidden */
1317
export { Payment, PaymentCreator, PaymentOpts, Stack, StackElement, } from './payments';
1418
export { Input as TxInput, Output as TxOutput } from './transaction';
1519
export { initEccLib } from './ecc_lib';

‎src/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Object.defineProperty(exports, 'Psbt', {
3535
return psbt_1.Psbt;
3636
},
3737
});
38+
/** @hidden */
3839
var ops_1 = require('./ops');
3940
Object.defineProperty(exports, 'opcodes', {
4041
enumerable: true,

0 commit comments

Comments
 (0)