OSDN Git Service

fix receiver bug
[bytom/pybtm.git] / README.md
1 pybtm
2 ======
3
4 - [1 Installation](#1-installation)
5 - [2 Usage](#2-usage)
6   - [2.1 Create entropy](#21-create-entropy)
7   - [2.2 Create mnemonics](#22-create-mnemonics)
8   - [2.3 Create seed](#23-create-seed)
9   - [2.4 Create root expanded private key](#24-create-root-expanded-private-key)
10   - [2.5 Create expanded public key](#25-create-expanded-public-key)
11   - [2.6 Create expanded private key](#26-create-expanded-private-key)
12   - [2.7 Create public key](#27-create-public-key)
13   - [2.8 Create child expanded private key](#28-create-child-expanded-private-key)
14   - [2.9 Create child expanded public key](#29-create-child-expanded-public-key)
15   - [2.10 Sign message](#210-sign-message)
16   - [2.11 Verify signature](#211-verify-signature)
17   - [2.12 Create new key](#212-create-new-key)
18   - [2.13 Create HD path](#213-create-hd-path)
19   - [2.14 Create control program](#214-create-control-program)
20   - [2.15 Create address](#215-create-address)
21   - [2.16 Create new address](#216-create-new-address)
22   - [2.17 Submit raw transaction](#217-submit-raw-transaction)
23   - [2.18 Decode raw transaction](#218-decode-raw-transaction)
24
25 Python3 implementation of the Bytom protocol.
26
27 ## 1 Installation
28
29 ```
30 $ pip install pybtm
31 ```
32
33 Requires:
34
35 - Python>=3.7
36
37 ## 2 Usage
38
39 ### 2.1 Create entropy
40
41 get_entropy() create 128 bits entropy.
42
43 Return:
44
45 - entropy_hexstr: 128 bits entropy.
46
47 ```python
48 >>> from pybtm import key
49 >>> key.get_entropy()
50 '100e2704b431f914e3262926bdba6fce'
51 ```
52
53 ### 2.2 Create mnemonics
54
55 get_mnemonic create 12 new mnemonics.
56
57 Parameter:
58
59 - entropy_hexstr(optional): 128 bits entropy, type is hex string.
60
61 Return:
62
63 - mnemonic_str: 12 mnemonics.
64
65 ```python
66 >>> key.get_mnemonic('089fe9bf0cac76760bc4b131d938669e')
67 'ancient young hurt bone shuffle deposit congress normal crack six boost despair'
68 ```
69
70 If no paramater is specified, it will return 12 new random mnemonics.
71
72 ```python
73 >>> from pybtm import key
74 >>> key.get_mnemonic()
75 'nothing gate perfect glide wink lizard journey negative load quote wrong reason'
76 ```
77
78 ### 2.3 Create seed
79
80 get_seed create 512 bits seed from 12 mnemonics.
81
82 Parameter:
83
84 - mnemonic_str: 12 mnemonics.
85
86 Return:
87
88 - seed_hexstr: 512 bits seed, type is hex string.
89
90 ```python
91 >>> from pybtm import key
92 >>> key.get_seed('ancient young hurt bone shuffle deposit congress normal crack six boost despair')
93 'afa3a86bbec2f40bb32833fc6324593824c4fc7821ed32eac1f762b5893e56745f66a6c6f2588b3d627680aa4e0e50efd25065097b3daa8c6a19d606838fe7d4'
94 ```
95
96 ### 2.4 Create root expanded private key
97
98 get_root_xprv create root expanded private key.
99
100 Parameter:
101
102 - seed_hexstr: 512 bits seed, type is hex string.
103
104 Return:
105
106 - root_xprv_hexstring: 512 bits seed, type is hex string.
107
108 ```python
109 >>> from pybtm import key
110 >>> key.get_root_xprv('afa3a86bbec2f40bb32833fc6324593824c4fc7821ed32eac1f762b5893e56745f66a6c6f2588b3d627680aa4e0e50efd25065097b3daa8c6a19d606838fe7d4')
111 '302a25c7c0a68a83fa043f594a2db8b44bc871fced553a8a33144b31bc7fb84887c9e75915bb6ba3fd0b9f94a60b7a5897ab9db6a48f888c2559132dba9152b0'
112 ```
113
114 ### 2.5 Create expanded public key
115
116 get_xpub create expanded public key.
117
118 Parameter:
119
120 - xprv_hexstr: 512 bits expanded private key, type is hex string.
121
122 Return:
123
124 - xpub_hexstr: 512 bits expanded public key, type is hex string.
125
126 ```python
127 >>> from pybtm import key
128 >>> xprv_hexstr = 'c003f4bcccf9ad6f05ad2c84fa5ff98430eb8e73de5de232bc29334c7d074759d513bc370335cac51d77f0be5dfe84de024cfee562530b4d873b5f5e2ff4f57c'
129 >>> key.get_xpub(xprv_hexstr)
130 '1b0541a7664cee929edb54d9ef21996b90546918a920a77e1cd6015d97c56563d513bc370335cac51d77f0be5dfe84de024cfee562530b4d873b5f5e2ff4f57c'
131 ```
132
133 ### 2.6 Create expanded private key
134
135 get_expanded_private_key create expanded private key.
136
137 Parameter:
138
139 - xprv_hexstr: 512 bits expanded private key, type is hex string.
140
141 Return:
142
143 - expanded_private_key_hexstr: 512 bits expanded private key, type is hex string.
144
145 ```python
146 >>> from pybtm import key
147 >>> xprv_hexstr = '406c82307bf7978d17f3ecfeea7705370e9faef2027affa86c8027c6e11a8a50e231e65bd97048850ae6c39d0f46b63ae70aa24f5aac7877727c430c2201e6d6'
148 >>> key.get_expanded_private_key(xprv_hexstr)
149 '406c82307bf7978d17f3ecfeea7705370e9faef2027affa86c8027c6e11a8a50d828bf44b1a109c2bbb4c72685858e2f2ab8b405beef1e4ecc12d1ed8511e8eb'
150 ```
151
152 ### 2.7 Create public key
153
154 get_public_key create 32 bytes public key.
155
156 Parameter:
157
158 - xpub_hexstr: 512 bits expanded public key, type is hex string.
159
160 Return:
161
162 - public_key_hexstr: 256 bits public key, type is hex string.
163
164 ```python
165 >>> from pybtm import key
166 >>> xpub_hexstr = 'ecc2bbb6c0492873cdbc81edf56bd896d3b644047879840e357be735b7fa7b6f4af1be7b8d71cc649ac4ca3816f9ccaf11bf49f4effb845f3c19e16eaf8bfcda'
167 >>> key.get_public_key(xpub_hexstr)
168 'ecc2bbb6c0492873cdbc81edf56bd896d3b644047879840e357be735b7fa7b6f'
169 ```
170
171 ### 2.8 Create child expanded private key
172
173 get_child_xprv create child private key.
174
175 Parameter:
176
177 - xprv_hexstr: 512 bits expanded private key, type is hex string.
178 - path_list: 010203 7906a1
179
180 Return:
181
182 - child_xprv_hexstr: 512 bits private key, type is hex string.
183
184 ```python
185 >>> from pybtm import key
186 >>> xprv_hexstr = 'c003f4bcccf9ad6f05ad2c84fa5ff98430eb8e73de5de232bc29334c7d074759d513bc370335cac51d77f0be5dfe84de024cfee562530b4d873b5f5e2ff4f57c'
187 >>> path_list = ['010203', '7906a1']
188 >>> key.get_child_xprv(xprv_hexstr, path_list)
189 '4853a0b00bdcb139e85855d9594e5f641b65218db7c50426946511397e094759bd9de7f2dcad9d7d45389bc94baecaec88aabf58f6e1d832b1f9995a93ec37ea'
190 ```
191
192 ### 2.9 Create child expanded public key
193
194 get_child_xpub create child public key.
195
196 Parameter:
197
198 - xpub_hexstr: 512 bits expanded public key, type is hex string.
199 - path_list: 010203 7906a1
200
201 Return:
202
203 - child_xpub_hexstr: 512 bits public key, type is hex string.
204
205 ```python
206 >>> from pybtm import key
207 >>> xpub_hexstr = '1b0541a7664cee929edb54d9ef21996b90546918a920a77e1cd6015d97c56563d513bc370335cac51d77f0be5dfe84de024cfee562530b4d873b5f5e2ff4f57c'
208 >>> path_list = ['010203', '7906a1']
209 >>> key.get_child_xpub(xpub_hexstr, path_list)
210 'e65c1a9714e2116c6e5d57dee188a53b98dc901a21def5a5ca46fcf78303f4f2bd9de7f2dcad9d7d45389bc94baecaec88aabf58f6e1d832b1f9995a93ec37ea'
211 ```
212
213 ### 2.10 Sign message
214
215 xprv_sign sign message.
216
217 Parameter:
218
219 - xprv_hexstr: 512 bits expanded private key, type is hex string.
220 - message_hexstr: message, type is hex string.
221
222 Return:
223
224 - signature_hexstr: 512 bits signature, type is hex string.
225
226 ```python
227 >>> from pybtm import key
228 >>> xprv_hexstr = '88c0c40fb54ef9c1b90af8cce8dc4c9d54f915074dde93f79ab61cedae03444101ff37ac4a07869214c2735bba0175e001abe608db18538e083e1e44430a273b'
229 >>> message_hexstr = '1246b84985e1ab5f83f4ec2bdf271114666fd3d9e24d12981a3c861b9ed523c6'
230 >>> key.xprv_sign(xprv_hexstr, message_hexstr)
231 'ab18f49b23d03295bc2a3f2a7d5bb53a2997bed733e1fc408b50ec834ae7e43f7da40fe5d9d50f6ef2d188e1d27f976aa2586cef1ba00dd098b5c9effa046306'
232 ```
233
234 ### 2.11 Verify signature
235
236 xpub_verify verify signature.
237
238 Parameter:
239
240 - xpub_hexstr: 512 bits expanded public key, type is hex string.
241 - message_hexstr: message, type is hex string.
242 - signature_hexstr: 512 bits signature, type is hex string.
243
244 Return:
245
246 - result: True or False.
247
248 ```python
249 >>> from pybtm import key
250 >>> xpub_hexstr = 'cb22ce197d342d6bb440b0bf13ddd674f367275d28a00f893d7f0b10817690fd01ff37ac4a07869214c2735bba0175e001abe608db18538e083e1e44430a273b'
251 >>> message_hexstr = '1246b84985e1ab5f83f4ec2bdf271114666fd3d9e24d12981a3c861b9ed523c6'
252 >>> signature_hexstr = 'ab18f49b23d03295bc2a3f2a7d5bb53a2997bed733e1fc408b50ec834ae7e43f7da40fe5d9d50f6ef2d188e1d27f976aa2586cef1ba00dd098b5c9effa046306'
253 >>> key.xpub_verify(xpub_hexstr, message_hexstr, signature_hexstr)
254 True
255 ```
256
257 ### 2.12 Create new key
258
259 get_new_key create new key.
260
261 Parameter:
262
263 - entropy_hexstr(optional): 128 bits entropy, type is hex string.
264 - mnemonic_str(optional): 12 mnemonics.
265
266 Return:
267
268 - entropy: 128 bits entropy.
269 - mnemonic: 12 mnemonics.
270 - seed: 512 bits seed.
271 - xprv: 512 bits expaneded private key.
272 - xpub: 512 bits expaneded public key.
273 - xprv_base64: xprv hex string qrcode base64.
274
275 ```python
276 >>> from pybtm import key
277 >>> r = key.get_new_key()
278 >>> r['entropy']
279 '8466b1128f92051361c9aa2de52d1bb0'
280 >>> r['mnemonic']
281 'love culture dwarf busy cake meadow mango crystal combine city eight genuine'
282 >>> r['seed']
283 '4d15bf0f72bad754987fdcd0628ea37af03ac24666019c6d362e0200c9b49bee35aa0a788ed09e3a86cd529df0a1c20ea6aa719cf1e0da4ffb15efbc38fba498'
284 >>> r['xprv']
285 'f09ad64c2714b45e23c75e4541ad771def99b97e6da16b0cc6bcdac045f4d34745b62093173fd8f9a67e1da4b81233bc947880b6ed4b9641cf8f5223212fa18d'
286 >>> r['xpub']
287 'ebcc4b14444adb207dd53fd89b2881b21e839de42a1b6687a5a9d83b82c1b5b645b62093173fd8f9a67e1da4b81233bc947880b6ed4b9641cf8f5223212fa18d'
288 >>> r['xprv_base64']
289 {'base64': '/9j/4AAQSkZJRgABAQAAAQABAAD...'}
290 ```
291
292 ```python
293 >>> from pybtm import key
294 >>> r = key.get_new_key(entropy_hexstr='4d33735a9e92f634d22aecbb4044038d')
295 >>> r['entropy']
296 '4d33735a9e92f634d22aecbb4044038d'
297 >>> r['mnemonic']
298 'essay oppose stove diamond control bounce emerge frown robust acquire abstract brick'
299 ```
300
301 ```python
302 >>> from pybtm import key
303 >>> r = key.get_new_key(mnemonic_str='ancient young hurt bone shuffle deposit congress normal crack six boost despair')
304 >>> r['entropy']
305 ''
306 >>> r['mnemonic']
307 'ancient young hurt bone shuffle deposit congress normal crack six boost despair'
308 >>> r['seed']
309 'afa3a86bbec2f40bb32833fc6324593824c4fc7821ed32eac1f762b5893e56745f66a6c6f2588b3d627680aa4e0e50efd25065097b3daa8c6a19d606838fe7d4'
310 ```
311
312 ### 2.13 Create HD path
313
314 get_path_from_index create HD path.
315
316 Parameter:
317
318 - account_index_int: 1, 2, 3, ..., type is hex string.
319 - address_index_int: 1, 2, 3, ..., type is hex string.
320 - change_bool: If receiver is change, change_bool is True, otherwise the change_bool is False.
321
322 Return:
323
324 - path_list: path list.
325 - path_str: path string.
326
327 ```python
328 >>> from pybtm import receiver
329 >>> account_index_int = 1
330 >>> address_index_int = 1
331 >>> change_bool = True
332 >>> receiver.get_path_from_index(account_index_int, address_index_int, change_bool)
333 {'path': ['2c000000', '99000000', '01000000', '01000000', '01000000'], 'path_str': 'm/44/153/1/1/1'}
334 ```
335
336 ### 2.14 Create control program
337
338 get_control_program create control program.
339
340 Parameter:
341
342 - account_index_int: account index, e.g. 1, 2, 3...
343 - address_index_int: address index, e.g. 1, 2, 3...
344 - change_bool: If receiver is change, change_bool is True, otherwise the change_bool is False.
345 - xpub_hexstr: 512 bits expanded public key, type is hex string.
346
347 Return:
348
349 - control_program_hexstr: type is hex string.
350
351 ```python
352 >>> from pybtm import receiver
353 >>> account_index_int = 1
354 >>> address_index_int = 1
355 >>> change_bool = False
356 >>> xpub_hexstr = '3c6664244d2d57168d173c4691dbf8741a67d972b2d3e1b0067eb825e2005d20c5eebd1c26ccad4de5142d7c339bf62cc1fb79a8b3e42a708cd521368dbc9286'
357 >>> receiver.get_control_program(account_index_int, address_index_int, change_bool, xpub_hexstr)
358 '0014052620b86a6d5e07311d5019dffa3864ccc8a6bd'
359 ```
360
361 ### 2.15 Create address
362
363 get_address create address from control program.
364
365 Parameter:
366
367 - control_program_hexstr: control program.
368 - network_str: 3 types of network is available: mainnet, testnet and solonet.
369
370 Return:
371
372 - address: bytom address.
373
374 ```python
375 >>> from pybtm import receiver
376 >>> control_program_hexstr = '001431f2b90b469e89361225aae370f73e5473b9852b'
377 >>> network_str = 'mainnet'
378 >>> receiver.get_address(control_program_hexstr, network_str)
379 'bm1qx8etjz6xn6ynvy394t3hpae723emnpft3nrwej'
380 ```
381
382 ### 2.16 Create new address
383
384 get_new_address create new address.
385
386 Parameter:
387
388 - xpub_hexstr: 512 bits expanded public key, type is hex string.
389 - account_index_int: account index, e.g. 1, 2, 3...
390 - address_index_int: address index, e.g. 1, 2, 3...
391 - change_bool: If receiver is change, change_bool is True, otherwise the change_bool is False.
392 - network_str: 3 types of network is available: mainnet, testnet and solonet.
393
394 Return:
395
396 - path: BIP44 HD path.
397 - control program: control program.
398 - address: bytom address.
399 - address_base64: bytom address image base64.
400
401 ```python
402 >>> from pybtm import receiver
403 >>> xpub_hexstr = '8fde12d7c9d6b6cbfbf344edd42f2ed86ae6270b36bab714af5fd5bb3b54adcec4265f1de85ece50f17534e42016ee9404a11fec94ddfadd4a064d27ef3f3f4c'
404 >>> account_index_int = 1
405 >>> address_index_int = 1
406 >>> change_bool = False
407 >>> network_str = 'solonet'
408 >>> receiver.get_new_address(xpub_hexstr, account_index_int, address_index_int, change_bool, network_str)
409 {'path': 'm/44/153/1/0/1', 'control_program': '00147640f3c34fe4b2b298e54e54a4692a47ce47aa5e', 'address': 'sm1qweq08s60ujet9x89fe22g6f2gl8y02j7lgr5v5', 'address_base64': '/9j/4AAQSkZJRgAB...'}
410 ```
411
412 ### 2.17 Submit raw transaction
413
414 submit_transaction submit transaction.
415
416 Parameter:
417
418 - raw_transaction_hexstr: raw transaction.
419 - submit_url: you can send raw transaction through submit_url.
420
421 Return:
422
423 - result: If submit transaction successfully, result is 1.
424
425 ```python
426 >>> from pybtm import transaction
427 >>> raw_transaction_hexstr = '070100010160015e5dfc352f9247985e92b2688a9a0a0e3e45a52f633c7d2c35cf6485fc1f03a89cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8094ebdc030101160014052620b86a6d5e07311d5019dffa3864ccc8a6bd630240988348a301c86563eb16105cc0c7e12e8cd1fbc7e9031933dac05a32d2a696bc77b83f25a99a4a9458d976c5327b8004918545a3fde567f28d805f741db54e0b20e87ca3acdebdcad9a1d0f2caecf8ce0dbfc73d060807a210c6f225488347961402013dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80b6f7f302011600147950bb5fcfb1c3fe14198c14ebd4ad85bb69bbc500013cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8084af5f011600141d8e1c2d71843f41e2131d7fd6df8b47e2cf56b900'
428 >>> submit_url = 'https://blockmeta.com/api/wisdom/broadcast-transaction'
429 >>> transaction.submit_transaction(raw_transaction_hexstr, submit_url)
430 '1'
431 ```
432
433 ```python
434 >>> from pybtm import transaction
435 >>> raw_transaction_hexstr = '07010001015f015d2f4a8f10afbc0448779fadd916a3f1b8518ffe0b7d20fdf470d8e9b4993ef2b4ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc0d8883200011600144a594e3e4cbbd87629476e7ee24c1637df66c0b76302406fd39079681118840fd6fd66cdff769f2d05d8520312e9dd559dc23c36a3cb3921e47cba233d5d2267eb0f128a908d1bab877e172e880d3f36dc6a5e5826540c202854e5c181f5a862edd190e413d75937549758ef4902e1475aac52623f0a239302013cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc09dd81001160014f63f68597df5c88a92e04229e0fd08a3584ade3b00013cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80e1eb1701160014664f28ec6ab8826a028658dc0d0d1f94c6e20fa300'
436 >>> submit_url = 'https://blockmeta.com/api/v2/broadcast-transaction'
437 >>> transaction.submit_transaction(raw_transaction_hexstr, submit_url)
438 '1'
439 ```
440
441 ### 2.18 Decode raw transaction
442
443 decode_raw_tx decode raw transaction.
444
445 Parameter:
446
447 - raw_transaction_hexstr: raw transaction, type is hex string.
448 - network_str: 3 types of network is available: mainnet, testnet and solonet.
449
450 Return:
451
452 - tx: tx dict.
453
454 ```python
455 >>> from pybtm import transaction
456 >>> raw_transaction_hexstr = '070100010161015f28b7b53d8dc90006bf97e0a4eaae2a72ec3d869873188698b694beaf20789f21ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8099c4d5990100011600149335b1cbd4a77b78e33315a0ed10a95b12e7ca48630240897e2d9d24a3b5faaed0579dee7597b401491595675f897504f8945b29d836235bd2fca72a3ad0cae814628973ebcd142d9d6cc92d0b2571b69e5370a98a340c208cb7fb3086f58db9a31401b99e8c658be66134fb9034de1d5c462679270b090702013effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80f9f8bc98010116001406ce4b689ba026ffd3a7ca65d1d059546d4b78a000013dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80c6868f01011600147929ef91997c827bebf60fa608f876ea27523c4700'
457 >>> network_str = 'solonet'
458 >>> transaction.decode_raw_tx(raw_transaction_hexstr, network_str)
459 {'fee': 20000000, 'inputs': [{'address': 'sm1qjv6mrj755aah3cenzksw6y9ftvfw0jjgk0l2mw', 'amount': 41250000000, 'asset_definition': {}, 'asset_id': 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', 'control_program': '00149335b1cbd4a77b78e33315a0ed10a95b12e7ca48', 'input_id': '6e3f378ed844b143a335e306f4ba26746157589c87e8fc8cba6463c566c56768', 'spent_output_id': 'f229ec6f403d586dc87aa2546bbe64c5f7b5f46eb13c6ee4823d03bc88a7cf17', 'type': 'spend', 'witness_arguments': ['897e2d9d24a3b5faaed0579dee7597b401491595675f897504f8945b29d836235bd2fca72a3ad0cae814628973ebcd142d9d6cc92d0b2571b69e5370a98a340c', '8cb7fb3086f58db9a31401b99e8c658be66134fb9034de1d5c462679270b0907']}], 'outputs': [{'address': 'sm1qqm8yk6ym5qn0l5a8efjar5ze23k5k79qnvtslj', 'amount': 40930000000, 'asset_definition': {}, 'asset_id': 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', 'control_program': '001406ce4b689ba026ffd3a7ca65d1d059546d4b78a0', 'id': '74c73266730d3c6ea32e8667ef9b867068736b84be240fe9fef205fa68bb7b95', 'position': 0, 'type': 'control'}, {'address': 'sm1q0y57lyve0jp8h6lkp7nq37rkagn4y0z8hvh6kq', 'amount': 300000000, 'asset_definition': {}, 'asset_id': 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', 'control_program': '00147929ef91997c827bebf60fa608f876ea27523c47', 'id': 'f115a833d0c302a5006032858a7ed3987f0feb2daf2a9f849384950e4766af51', 'position': 1, 'type': 'control'}], 'size': 333, 'time_range': 0, 'tx_id': '814a73dd57bae67c604f9cbc696cbc42035577423408cb9267136ed971e2bf63', 'version': 1}
460 ```