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 ##### Example
 503
 504 ```java
 505 //list all transactions
 506 List<Transaction> transactionList = new Transaction.QueryBuilder().list(client);
 507 ```
 508
 509 ----
 510
 511 #### listTransactionsById
 512
 513 ```java
 514 List<Transaction> listById(Client client);
 515 ```
 516
 517 ##### Parameters
 518
 519 - `Client` - *Client*, Client object that makes requests to the core.
 520
 521 ##### Returns
 522
 523 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 524
 525 ##### Example
 526
 527 ```java
 528 String tx_id = "f04d4d9b2580ff6496f9f08d903de5a2365975fb8d65b66ca4259f152c5dd134";
 529 //list all transactions by tx_id
 530 List<Transaction> transactionList = new Transaction.QueryBuilder().setTxId(tx_id).list(client);
 531 ```
 532
 533 ----
 534
 535 #### listTransactionsByAccountId
 536
 537 ```java
 538 List<Transaction> listByAccountId(Client client);
 539 ```
 540
 541 ##### Parameters
 542
 543 - `Client` - *Client*, Client object that makes requests to the core.
 544
 545 ##### Returns
 546
 547 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 548
 549 ##### Example
 550
 551 ```java
 552 String account_id = "0E6KP8C100A02";
 553 //list all transactions by account_id
 554 List<Transaction> transactionList = new Transaction.QueryBuilder().setAccountId(account_id).list(client);
 555 ```
 556
 557 ## Wallet API
 558
 559
 560 #### backupWallet
 561
 562 ```java
 563 Wallet backupWallet(Client client);
 564 ```
 565
 566 ##### Parameters
 567
 568 - `Client` - *Client*, Client object that makes requests to the core.
 569
 570 ##### Returns
 571
 572 - `Wallet` - *wallet*, a Wallet object
 573
 574 ----
 575
 576 #### restoreWallet
 577
 578 ```java
 579 void restoreWallet(Client client ,Object accountImage, Object assetImage , Object keyImages);
 580 ```
 581
 582 ##### Parameters
 583
 584 `Object`:
 585 - `Client` - *Client*, Client object that makes requests to the core.
 586 - `Object` - *account_image*, account image.
 587 - `Object` - *asset_image*, asset image.
 588 - `Object` - *key_images*, key image.
 589
 590 ##### Returns
 591
 592 none if restore wallet success.
 593
 594
 595 ## Access Token API
 596
 597 ```java
 598 //example
 599 AccessToken accessToken = new AccessToken.Builder().setId("sheng").create(client);
 600
 601 List<AccessToken> tokenList = AccessToken.list(client);
 602
 603 String secret = "5e37378eb59de6b10e60f2247ebf71c4955002e75e0cd31ede3bf48813a0a799";
 604 AccessToken.check(client, "sheng", secret);
 605 ```
 606
 607 #### createAccessToken
 608
 609 ```java
 610 AccessToken create(Client client);
 611 ```
 612
 613 ##### Parameters
 614
 615 - `Client` - *Client*, Client object that makes requests to the core.
 616
 617 ##### Returns
 618
 619 - `AccessToken` - *accessToken*, an AccessToken object.
 620
 621 ----
 622
 623 #### listAccessTokens
 624
 625 ```java
 626 List<AccessToken> list(Client client);
 627 ```
 628
 629 ##### Parameters
 630
 631 - `Client` - *Client*, Client object that makes requests to the core.
 632
 633 ##### Returns
 634
 635 - `Array of Object`, access token array.
 636
 637 ----
 638
 639 #### deleteAccessToken
 640
 641 ```java
 642 void delete(Client client, String id);
 643 ```
 644
 645 ##### Parameters
 646
 647 - `Client` - *Client*, Client object that makes requests to the core.
 648 - `String` - *id*, token ID.
 649
 650 ##### Returns
 651
 652 none if the access token is deleted successfully.
 653
 654 ----
 655
 656 #### checkAccessToken
 657
 658 ```java
 659 void check(Client client, String id, String secret);
 660 ```
 661
 662 ##### Parameters
 663
 664 - `Client` - *Client*, Client object that makes requests to the core.
 665 - `String` - *id*, token ID.
 666 - `String` - *secret*, secret of token, the second part of the colon division for token.
 667
 668 ##### Returns
 669
 670 none if the access token is checked valid.
 671
 672
 673 ## Block API
 674
 675
 676 #### getBlockCount
 677
 678 ```java
 679 Integer getBlockCount(Client client);
 680 ```
 681
 682 ##### Parameters
 683
 684 none
 685
 686 ##### Returns
 687
 688 - `Integer` - *block_count*, recent block height of the blockchain.
 689
 690 ----
 691
 692 #### getBlockHash
 693
 694 ```java
 695 String getBlockHash(Client client);
 696 ```
 697
 698 ##### Parameters
 699
 700 none
 701
 702 ##### Returns
 703
 704 - `String` - *block_hash*, recent block hash of the blockchain.
 705
 706 ----
 707
 708 #### getBlock
 709 ```php
 710 Block getBlock(Client client);
 711 ```
 712
 713 ##### Parameters
 714
 715 - `Client` - *Client*, Client object that makes requests to the core.
 716
 717 ##### Returns
 718
 719 - `Block` - *block*, a Block object.
 720
 721 ----
 722
 723 #### getBlockHeader
 724
 725 ```java
 726 BlockHeader getBlockHeader(Client client);
 727 ```
 728
 729 ##### Parameters
 730
 731 - `Client` - *Client*, Client object that makes requests to the core.
 732
 733 ##### Returns
 734
 735 - `BlockHeader` - *blockHeader*, header of block.
 736
 737 ----
 738
 739 #### getDifficulty
 740
 741 ```java
 742 BlockDifficulty getBlockDifficulty(Client client);
 743 ```
 744
 745 ##### Parameters
 746
 747 - `Client` - *Client*, Client object that makes requests to the core.
 748
 749 ##### Returns
 750
 751 - `BlockDifficulty` - *blockDifficulty*, a BlockDifficulty object
 752
 753 ----
 754
 755 #### getHashRate
 756
 757 ```java
 758 BlockHashRate getHashRate(Client client);
 759 ```
 760
 761 ##### Parameters
 762
 763 - `Client` - *Client*, Client object that makes requests to the core.
 764
 765 ##### Returns
 766
 767 - `BlockHashRate` - *blockHashRate*, a BlockHashRate object
 768
 769 ## Mining API
 770
 771
 772 #### isMining
 773
 774 ```java
 775 Boolean isMining(Client client);
 776 ```
 777
 778 ##### Parameters
 779
 780 - `Client` - *Client*, Client object that makes requests to the core.
 781
 782 ##### Returns
 783
 784 - `Boolean` - *is_mining*, whether the node is mining.
 785
 786 ----
 787
 788 #### setMining
 789
 790 ```java
 791 void setMining(Client client, Boolean isMining);
 792 ```
 793
 794 ##### Parameters
 795
 796 - `Client` - *Client*, Client object that makes requests to the core.
 797 - `Boolean` - *is_mining*, whether the node is mining.
 798
 799
 800 ## Other API
 801
 802
 803 #### netInfo
 804
 805 ```java
 806 NetInfo getNetInfo(Client client);
 807 ```
 808
 809 ##### Parameters
 810
 811 - `Client` - *Client*, Client object that makes requests to the core.
 812
 813 ##### Returns
 814
 815 - `NetInfo` - *netInfo*, a NetInfo object.
 816
 817 ----
 818
 819 #### gasRate
 820
 821 ```java
 822 Gas gasRate(Client client);
 823 ```
 824
 825 ##### Parameters
 826
 827 - `Client` - *Client*, Client object that makes requests to the core.
 828
 829 ##### Returns
 830
 831 - `Gas` - *gas*, a Gas object.
 832
 833 ----
 834
 835 #### verifyMessage
 836
 837 ```java
 838 Boolean verifyMessage(Client client);
 839 ```
 840
 841 ##### Parameters
 842
 843 - `Client` - *Client*, Client object that makes requests to the core.
 844
 845 ##### Returns
 846
 847 - `Boolean` - *result*, verify result.
 848
 849 ----
 850
 851 #### getWork
 852
 853 ```java
 854 MinerWork getWork(Client client);
 855 ```
 856
 857 ##### Parameters
 858
 859 - `Client` - *Client*, Client object that makes requests to the core.
 860
 861 ##### Returns
 862
 863 - `MinerWork` - *minerWork*, a MinerWork object.
 864
 865 ----
 866
 867 #### submitWork
 868
 869 ```java
 870 void submiWork(Client client, String blockHeader);
 871 ```
 872
 873 ##### Parameters
 874
 875 - `Client` - *Client*, Client object that makes requests to the core.
 876 - `String` - *block_header*, raw block header.
 877
 878 ##### Returns
 879
 880 none if the work is submitted successfully.