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