doc/index.md

   1 # Java SDK documentation
   2
   3 This page will document the API classes and ways to properly use the API.
   4 Subsequent new releases also maintain backward compatibility with this class approach.
   5
   6 ## Basic Usage
   7
   8 ```
   9 public static Client generateClient() throws BytomException {
  10     String coreURL = Configuration.getValue("bytom.api.url");
  11     String accessToken = Configuration.getValue("client.access.token");
  12     if (coreURL == null || coreURL.isEmpty()) {
  13         coreURL = "http://127.0.0.1:9888/";
  14     }
  15     return new Client(coreURL, accessToken);
  16 }
  17
  18 Client client = TestUtils.generateClient();
  19 ```
  20
  21 ## Usage
  22
  23 * [`Step 1: Create a key`](#create-a-key)
  24 * [`Step 2: Create an account`](#create-an-account)
  25 * [`Step 3: Create an receiver`](#create-an-receiver)
  26 * [`Step 4: Create an asset`](#create-an-asset)
  27 * [`Step 5: Issue asset`](#issue-asset)
  28     * [`Firstly build the transaction`](#firstly-build-the-transaction)
  29     * [`Secondly sign the transaction`](#secondly-sign-the-transaction)
  30     * [`Finally submit the transaction`](#finally-submit-the-transaction)
  31
  32 > For more details, see [`API methods`](#api-methods)
  33
  34 ## Create a key
  35
  36 ```java
  37 String alias = "test";
  38 String password = "123456";
  39
  40 Key.Builder builder = new Key.Builder().setAlias(alias).setPassword(password);
  41 Key key = Key.create(client, builder);
  42 ```
  43
  44 ## Create an account
  45
  46 ```java
  47 String alias = "sender-account";
  48 Integer quorum = 1;
  49 List<String> root_xpubs = new ArrayList<String>();
  50 root_xpubs.add(senderKey.xpub);
  51
  52 Account.Builder builder = new Account.Builder().setAlias(alias).setQuorum(quorum).setRootXpub(root_xpubs);
  53
  54 Account account = Account.create(client, builder);
  55 ```
  56
  57 ## Create an receiver
  58
  59 ```java
  60 String alias = receiverAccount.alias;
  61 String id = receiverAccount.id;
  62
  63 Account.ReceiverBuilder receiverBuilder = new Account.ReceiverBuilder().setAccountAlias(alias).setAccountId(id);
  64 Receiver receiver = receiverBuilder.create(client);
  65 ```
  66
  67 ## Create an asset
  68
  69 ```java
  70  String alias = "receiver-asset";
  71
  72 List<String> xpubs = receiverAccount.xpubs;
  73
  74 Asset.Builder builder = new Asset.Builder()
  75                         .setAlias(alias)
  76                         .setQuorum(1)
  77                         .setRootXpubs(xpubs);
  78 receiverAsset = builder.create(client);
  79 ```
  80
  81 ## Issue asset
  82
  83 ### Firstly build the transaction
  84
  85 ```java
  86 Transaction.Template controlAddress = new Transaction.Builder()
  87         .addAction(
  88                 new Transaction.Action.SpendFromAccount()
  89                         .setAccountId(senderAccount.id)
  90                         .setAssetId(senderAsset.id)
  91                         .setAmount(300000000)
  92         )
  93         .addAction(
  94                 new Transaction.Action.ControlWithAddress()
  95                         .setAddress(receiverAddress.address)
  96                         .setAssetId(senderAsset.id)
  97                         .setAmount(200000000)
  98         ).build(client);
  99 ```
 100
 101 ### Secondly sign the transaction
 102
 103 ```java
 104 Transaction.Template singer = new Transaction.SignerBuilder().sign(client,
 105         controlAddress, "123456");
 106 ```
 107
 108 ### Finally submit the transaction
 109
 110 ```java
 111 Transaction.SubmitResponse txs = Transaction.submit(client, singer);
 112 ```
 113
 114 ----
 115
 116 ## API methods
 117
 118 * [`Key API`](#key-api)
 119 * [`Account API`](#account-api)
 120 * [`Asset API`](#asset-api)
 121 * [`Transaction API`](#transaction-api)
 122 * [`Wallet API`](#wallet-api)
 123 * [`Access Token API`](#access-token-api)
 124 * [`Block API`](#block-api)
 125 * [`Mining API`](#mining-api)
 126 * [`Other API`](#other-api)
 127
 128 ## Key API
 129
 130
 131 #### createKey
 132
 133 ```java
 134 Key create(Client client, Builder builder);
 135 ```
 136
 137 ##### Parameters
 138
 139 - `Client` - *client*, Client object that makes requests to the core.
 140 - `Key.Builder` - *builder*, Builder object that builds request parameters.
 141
 142 ##### Returns
 143
 144 - `Key` - *key*, Key object.
 145
 146 ----
 147
 148 #### listKeys
 149
 150 ```java
 151 List<Key> list(Client client);
 152 ```
 153
 154 ##### Parameters
 155
 156 - `Client` - *client*, Client object that makes requests to the core.
 157
 158 ##### Returns
 159
 160 - `List of Key`, *List<Key>*, an ArrayList object contains Key objects.
 161
 162 ----
 163
 164 #### deleteKey
 165
 166 ```java
 167 void delete(Client client, String xpub, String password);
 168 ```
 169
 170 ##### Parameters
 171
 172 - `Client` - *client*, Client object that makes requests to the core.
 173 - `String` - *xpub*, pubkey of the key.
 174 - `String` - *password*, password of the key.
 175
 176 ##### Returns
 177
 178 none if the key is deleted successfully.
 179
 180 ----
 181
 182 #### resetKeyPassword
 183
 184 ```java
 185 void resetPwd(Client client, String xpub, String oldPwd, String newPwd);
 186 ```
 187
 188 ##### Parameters
 189
 190 - `Client` - *client*, Client object that makes requests to the core.
 191 - `String` - *xpub*, pubkey of the key.
 192 - `String` - *oldPwd*, old password of the key.
 193 - `String` - *newPwd*, new password of the key.
 194
 195 ##### Returns
 196
 197 none if the key password is reset successfully.
 198
 199
 200 ## Account API
 201
 202
 203 #### createAccount
 204
 205 ```java
 206 Account create(Client client, Builder builder);
 207 ```
 208 ##### Parameters
 209
 210 - `Client` - *client*, Client object that makes requests to the core.
 211 - `Account.Builder` - *builder*, Builder object that builds request parameters.
 212
 213 ##### Returns
 214
 215 - `Account` - *account*, Account object.
 216
 217 ----
 218
 219 #### listAccounts
 220
 221 ```java
 222 List<Account> list(Client client);
 223 ```
 224
 225 ##### Parameters
 226
 227 - `Client` - *client*, Client object that makes requests to the core.
 228
 229 ##### Returns
 230
 231 - `List of Account`, *List<Account>*, an ArrayList object contains Account objects.
 232
 233 ----
 234
 235 #### deleteAccount
 236
 237 ```java
 238 void delete(Client client, String account_info);
 239 ```
 240
 241 ##### Parameters
 242
 243 - `Client` - *client*, Client object that makes requests to the core.
 244 - `String` - *account_info*, alias or ID of account.
 245
 246 ##### Returns
 247
 248 none if the account is deleted successfully.
 249
 250 ----
 251
 252 #### createAccountReceiver
 253
 254 ```java
 255 Receiver create(Client client);
 256 ```
 257
 258 ##### Parameters
 259
 260 - `Client` - *client*, Client object that makes requests to the core.
 261
 262 ##### Returns
 263
 264 - `Receiver` - *receiver*, Receiver object.
 265
 266
 267 ----
 268
 269 #### listAddresses
 270
 271 ```java
 272 List<Address> list(Client client);
 273 ```
 274
 275 ##### Parameters
 276
 277 - `Client` - *client*, Client object that makes requests to the core.
 278
 279 ##### Returns
 280
 281 - `List of Address`, *List<Address>*, an ArrayList object contains Address objects.
 282
 283 ----
 284
 285 #### validateAddress
 286
 287 ```java
 288 Address validate(Client client, String address);
 289 ```
 290
 291 ##### Parameters
 292
 293 - `Client` - *Client*, Client object that makes requests to the core.
 294 - `String` - *address*, address of account.
 295
 296 ##### Returns
 297
 298 - `Address` - *address*, an Address object.
 299
 300
 301 ## Asset API
 302
 303
 304 #### createAsset
 305
 306 ```java
 307 Asset create(Client client);
 308 ```
 309
 310 ##### Parameters
 311
 312 - `Client` - *Client*, Client object that makes requests to the core.
 313
 314 ##### Returns
 315
 316 - `Asset` - *asset*, an Asset object.
 317
 318 ----
 319
 320 #### getAsset
 321
 322 ```java
 323 Asset get(Client client);
 324 ```
 325
 326 ##### Parameters
 327
 328 - `Client` - *Client*, Client object that makes requests to the core.
 329
 330 ##### Returns
 331
 332 - `Asset` - *asset*, an Asset object.
 333
 334 ----
 335
 336 #### listAssets
 337
 338 ```java
 339 List<Asset> list(Client client);
 340 ```
 341
 342 ##### Parameters
 343
 344 - `Client` - *Client*, Client object that makes requests to the core.
 345
 346 ##### Returns
 347
 348 - `List of Asset`, *List<Asset>*, an ArrayList object contains Asset objects.
 349
 350 ----
 351
 352 #### updateAssetAlias
 353
 354 ```java
 355 void update(Client client);
 356 ```
 357
 358 ##### Parameters
 359
 360 - `Client` - *Client*, Client object that makes requests to the core.
 361
 362 ##### Returns
 363
 364 none if the asset alias is updated success.
 365
 366 ----
 367
 368 #### listBalances
 369
 370 ```java
 371 List<Balance> list(Client client);
 372 ```
 373
 374 ##### Parameters
 375
 376 - `Client` - *Client*, Client object that makes requests to the core.
 377
 378 ##### Returns
 379
 380 - `List of Balance`, an ArrayList object contains Balance objects.
 381
 382 ----
 383
 384 #### listUnspentOutPuts
 385
 386 ```java
 387 List<UnspentOutput> list(Client client);
 388 ```
 389
 390 ##### Parameters
 391
 392 - `Client` - *Client*, Client object that makes requests to the core.
 393
 394 ##### Returns
 395
 396 - `List of UnspentOutput`, an ArrayList object contains UnspentOutput objects.
 397
 398
 399 ## Transaction API
 400
 401
 402 #### buildTransaction
 403
 404 ```java
 405 Template build(Client client);
 406 ```
 407
 408 ##### Parameters
 409
 410 - `Client` - *Client*, Client object that makes requests to the core.
 411
 412 ##### Returns
 413
 414 - `Template` - *template*, a template object.
 415
 416 ----
 417
 418 #### signTransaction
 419
 420 ```java
 421 Template sign(Client client, Template template, String password);
 422 ```
 423
 424 ##### Parameters
 425
 426 `Object`:
 427
 428 - `Client` - *Client*, Client object that makes requests to the core.
 429 - `Template` - *template*, a template object.
 430 - `String` - *password*, signature of the password.
 431
 432 ##### Returns
 433
 434 - `Template` - *template*, a template object.
 435
 436 ----
 437
 438 #### submitTransaction
 439
 440 ```java
 441 SubmitResponse submit(Client client, Template template);
 442 ```
 443
 444 ##### Parameters
 445
 446 - `Client` - *Client*, Client object that makes requests to the core.
 447 - `Template` - *template*, a template object.
 448
 449 ##### Returns
 450
 451 - `SubmitResponse` - *submitResponse*, a SubmitResponse object
 452
 453 ----
 454
 455 #### estimateTransactionGas
 456
 457 ```java
 458 TransactionGas estimateGas(Client client, Template template);
 459 ```
 460
 461 ##### Parameters
 462
 463 - `Client` - *Client*, Client object that makes requests to the core.
 464 - `Template` - *template*, a template object.
 465
 466 ##### Returns
 467
 468 - `TransactionGas` - *transactionGas*, a TransactionGas object
 469
 470 ----
 471
 472 #### getTransaction
 473
 474 ```java
 475 Transaction get(Client client);
 476 ```
 477
 478 ##### Parameters
 479
 480 - `Client` - *Client*, Client object that makes requests to the core.
 481
 482 ##### Returns
 483
 484 - `Transaction` - *transaction*, a Transaction object
 485
 486 ----
 487
 488 #### listTransactions
 489
 490 ```java
 491 List<Transaction> list(Client client);
 492 ```
 493
 494 ##### Parameters
 495
 496 - `Client` - *Client*, Client object that makes requests to the core.
 497
 498 ##### Returns
 499
 500 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 501
 502 ## Wallet API
 503
 504
 505 #### backupWallet
 506
 507 ```java
 508 Wallet backupWallet(Client client);
 509 ```
 510
 511 ##### Parameters
 512
 513 - `Client` - *Client*, Client object that makes requests to the core.
 514
 515 ##### Returns
 516
 517 - `Wallet` - *wallet*, a Wallet object
 518
 519 ----
 520
 521 #### restoreWallet
 522
 523 ```java
 524 void restoreWallet(Client client ,Object accountImage, Object assetImage , Object keyImages);
 525 ```
 526
 527 ##### Parameters
 528
 529 `Object`:
 530 - `Client` - *Client*, Client object that makes requests to the core.
 531 - `Object` - *account_image*, account image.
 532 - `Object` - *asset_image*, asset image.
 533 - `Object` - *key_images*, key image.
 534
 535 ##### Returns
 536
 537 none if restore wallet success.
 538
 539
 540 ## Access Token API
 541
 542 ```java
 543 //example
 544 AccessToken accessToken = new AccessToken.Builder().setId("sheng").create(client);
 545
 546 List<AccessToken> tokenList = AccessToken.list(client);
 547
 548 String secret = "5e37378eb59de6b10e60f2247ebf71c4955002e75e0cd31ede3bf48813a0a799";
 549 AccessToken.check(client, "sheng", secret);
 550 ```
 551
 552 #### createAccessToken
 553
 554 ```java
 555 AccessToken create(Client client);
 556 ```
 557
 558 ##### Parameters
 559
 560 - `Client` - *Client*, Client object that makes requests to the core.
 561
 562 ##### Returns
 563
 564 - `AccessToken` - *accessToken*, an AccessToken object.
 565
 566 ----
 567
 568 #### listAccessTokens
 569
 570 ```java
 571 List<AccessToken> list(Client client);
 572 ```
 573
 574 ##### Parameters
 575
 576 - `Client` - *Client*, Client object that makes requests to the core.
 577
 578 ##### Returns
 579
 580 - `Array of Object`, access token array.
 581
 582 ----
 583
 584 #### deleteAccessToken
 585
 586 ```java
 587 void delete(Client client, String id);
 588 ```
 589
 590 ##### Parameters
 591
 592 - `Client` - *Client*, Client object that makes requests to the core.
 593 - `String` - *id*, token ID.
 594
 595 ##### Returns
 596
 597 none if the access token is deleted successfully.
 598
 599 ----
 600
 601 #### checkAccessToken
 602
 603 ```java
 604 void check(Client client, String id, String secret);
 605 ```
 606
 607 ##### Parameters
 608
 609 - `Client` - *Client*, Client object that makes requests to the core.
 610 - `String` - *id*, token ID.
 611 - `String` - *secret*, secret of token, the second part of the colon division for token.
 612
 613 ##### Returns
 614
 615 none if the access token is checked valid.
 616
 617
 618 ## Block API
 619
 620
 621 #### getBlockCount
 622
 623 ```java
 624 Integer getBlockCount(Client client);
 625 ```
 626
 627 ##### Parameters
 628
 629 none
 630
 631 ##### Returns
 632
 633 - `Integer` - *block_count*, recent block height of the blockchain.
 634
 635 ----
 636
 637 #### getBlockHash
 638
 639 ```java
 640 String getBlockHash(Client client);
 641 ```
 642
 643 ##### Parameters
 644
 645 none
 646
 647 ##### Returns
 648
 649 - `String` - *block_hash*, recent block hash of the blockchain.
 650
 651 ----
 652
 653 #### getBlock
 654 ```php
 655 Block getBlock(Client client);
 656 ```
 657
 658 ##### Parameters
 659
 660 - `Client` - *Client*, Client object that makes requests to the core.
 661
 662 ##### Returns
 663
 664 - `Block` - *block*, a Block object.
 665
 666 ----
 667
 668 #### getBlockHeader
 669
 670 ```java
 671 BlockHeader getBlockHeader(Client client);
 672 ```
 673
 674 ##### Parameters
 675
 676 - `Client` - *Client*, Client object that makes requests to the core.
 677
 678 ##### Returns
 679
 680 - `BlockHeader` - *blockHeader*, header of block.
 681
 682 ----
 683
 684 #### getDifficulty
 685
 686 ```java
 687 BlockDifficulty getBlockDifficulty(Client client);
 688 ```
 689
 690 ##### Parameters
 691
 692 - `Client` - *Client*, Client object that makes requests to the core.
 693
 694 ##### Returns
 695
 696 - `BlockDifficulty` - *blockDifficulty*, a BlockDifficulty object
 697
 698 ----
 699
 700 #### getHashRate
 701
 702 ```java
 703 BlockHashRate getHashRate(Client client);
 704 ```
 705
 706 ##### Parameters
 707
 708 - `Client` - *Client*, Client object that makes requests to the core.
 709
 710 ##### Returns
 711
 712 - `BlockHashRate` - *blockHashRate*, a BlockHashRate object
 713
 714 ## Mining API
 715
 716
 717 #### isMining
 718
 719 ```java
 720 Boolean isMining(Client client);
 721 ```
 722
 723 ##### Parameters
 724
 725 - `Client` - *Client*, Client object that makes requests to the core.
 726
 727 ##### Returns
 728
 729 - `Boolean` - *is_mining*, whether the node is mining.
 730
 731 ----
 732
 733 #### setMining
 734
 735 ```java
 736 void setMining(Client client, Boolean isMining);
 737 ```
 738
 739 ##### Parameters
 740
 741 - `Client` - *Client*, Client object that makes requests to the core.
 742 - `Boolean` - *is_mining*, whether the node is mining.
 743
 744
 745 ## Other API
 746
 747
 748 #### netInfo
 749
 750 ```java
 751 NetInfo getNetInfo(Client client);
 752 ```
 753
 754 ##### Parameters
 755
 756 - `Client` - *Client*, Client object that makes requests to the core.
 757
 758 ##### Returns
 759
 760 - `NetInfo` - *netInfo*, a NetInfo object.
 761
 762 ----
 763
 764 #### gasRate
 765
 766 ```java
 767 Gas gasRate(Client client);
 768 ```
 769
 770 ##### Parameters
 771
 772 - `Client` - *Client*, Client object that makes requests to the core.
 773
 774 ##### Returns
 775
 776 - `Gas` - *gas*, a Gas object.
 777
 778 ----
 779
 780 #### verifyMessage
 781
 782 ```java
 783 Boolean verifyMessage(Client client);
 784 ```
 785
 786 ##### Parameters
 787
 788 - `Client` - *Client*, Client object that makes requests to the core.
 789
 790 ##### Returns
 791
 792 - `Boolean` - *result*, verify result.
 793
 794 ----
 795
 796 #### getWork
 797
 798 ```java
 799 MinerWork getWork(Client client);
 800 ```
 801
 802 ##### Parameters
 803
 804 - `Client` - *Client*, Client object that makes requests to the core.
 805
 806 ##### Returns
 807
 808 - `MinerWork` - *minerWork*, a MinerWork object.
 809
 810 ----
 811
 812 #### submitWork
 813
 814 ```java
 815 void submiWork(Client client, String blockHeader);
 816 ```
 817
 818 ##### Parameters
 819
 820 - `Client` - *Client*, Client object that makes requests to the core.
 821 - `String` - *block_header*, raw block header.
 822
 823 ##### Returns
 824
 825 none if the work is submitted successfully.